feat!: consolidate and rename CLI environment variables

[nicknisi]

What & why

The CLI's environment-variable surface had grown large and inconsistent. This consolidates it.

Removed (derived instead)

• WORKOS_LLM_GATEWAY_URL → derived as ${WORKOS_API_URL}/llm-gateway
• WORKOS_TELEMETRY_URL → derived as ${WORKOS_API_URL}/cli

Both endpoints live under the WorkOS API host, so they're now derived from the single WORKOS_API_URL base. api.workos.com is no longer hardcoded in three places, and setting WORKOS_API_URL alone reroutes the API, gateway, and telemetry together.

Removed (redundant)

• WORKOS_NO_PROMPT → use WORKOS_MODE=agent

It was a legacy alias that mapped to agent interaction + JSON output. WORKOS_MODE=agent already does exactly that (JSON is forced via resolveEffectiveOutputMode), and it's self-documenting — NO_PROMPT described one side effect and hid the other.

Renamed (prefix consistency)

• INSTALLER_DEV → WORKOS_DEV
• INSTALLER_DISABLE_PROXY → WORKOS_DISABLE_PROXY

Anti-drift guard

The workos debug env catalog had already rotted (missing WORKOS_AGENT, WORKOS_SECRET_KEY, WORKOS_CLIENT_ID, and others). Fixed it, and added a test that scans src/ for process.env.WORKOS_* / destructured env.WORKOS_* reads and fails if any isn't cataloged — so the list can't silently drift again.

Breaking change

feat!: → release-please will cut 0.18.0 (minor, per bump-minor-pre-major) with a BREAKING CHANGES changelog entry. Real-world risk is low: 4 of the 5 vars are internal/developer-only, and WORKOS_NO_PROMPT is largely redundant with non-TTY auto-detection.

Verification

• pnpm typecheck ✅
• pnpm test ✅ (2092 passing)
• pnpm build ✅
• Verified the new guard test fails on drift for both process.env.X and destructured env.X reads.

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

[greptile-apps]

Greptile Summary

This PR consolidates the CLI's environment-variable surface by removing WORKOS_NO_PROMPT (replaced by WORKOS_MODE=agent via resolveEffectiveOutputMode), deriving LLM gateway and telemetry URLs from a single WORKOS_API_URL base, and renaming the INSTALLER_* prefix vars to WORKOS_*. It also adds an anti-drift guard that scans src/ for process.env.WORKOS_* reads and fails if any aren't in the catalog.

• URL derivation refactored: getLlmGatewayUrl() and getTelemetryUrl() are now pure derivations, with trailing-slash normalization — overriding a single env var now reroutes all three endpoints atomically.
• WORKOS_NO_PROMPT removed: Interaction mode + JSON output coupling now lives in resolveEffectiveOutputMode() rather than resolveOutputMode(), so agent mode always forces JSON regardless of TTY state.
• Catalog drift guard added: env-var-catalog.spec.ts performs a bidirectional check to keep workos debug env accurate going forward.

Confidence Score: 5/5

The change is safe to merge — it is a well-scoped rename/consolidation with no functional regressions in the env-var resolution logic.

All five removed/renamed variables have correct callsite updates throughout the codebase. The new URL-derivation logic in urls.ts is simple and covered by the integration test. The resolveEffectiveOutputMode coupling correctly replicates the WORKOS_NO_PROMPT behavior for WORKOS_MODE=agent. The anti-drift guard closes a real maintenance gap. No new issues were found beyond what the prior review thread already identified.

src/commands/debug.ts — the raw-value exposure of WORKOS_API_KEY in workos debug env output is a pre-existing concern raised in the prior thread that remains unaddressed.

Important Files Changed

Filename	Overview
src/utils/urls.ts	Core refactor: LLM gateway and telemetry URLs are now derived from getWorkOSApiUrl() with trailing-slash normalization; getLlmGatewayUrlFromHost alias removed cleanly.
src/commands/debug.ts	Catalog extended with WORKOS_CLIENT_ID, WORKOS_AGENT, doctor-check vars, and renamed WORKOS_DEV/WORKOS_DISABLE_PROXY; WORKOS_API_KEY raw value still printed in plain text (flagged in prior thread).
src/commands/env-var-catalog.spec.ts	New bidirectional drift guard scans non-spec TS for dot-access WORKOS_* reads; CATALOG_ONLY escape hatch for non-dot-access patterns is clearly documented.
src/utils/interaction-mode.ts	WORKOS_NO_PROMPT branch and workos_no_prompt source type cleanly removed; InteractionModeSource union narrowed accordingly.
src/utils/output.ts	WORKOS_NO_PROMPT check removed from resolveOutputMode; resolveEffectiveOutputMode correctly forces json for agent and ci interaction sources.
src/lib/settings.ts	getLlmGatewayUrl and getTelemetryUrl removed from settings; llmGatewayUrl/telemetryUrl fields dropped from InstallerConfig interface and config object.
src/bin-command-telemetry.integration.spec.ts	WORKOS_TELEMETRY_URL replaced by WORKOS_API_URL pointing to unroutable host; comment correctly explains the scope change.
src/lib/agent-interface.ts	INSTALLER_DISABLE_PROXY renamed to WORKOS_DISABLE_PROXY; getLlmGatewayUrlFromHost import replaced with getLlmGatewayUrl from urls.ts.
src/cli.config.ts	Removed hardcoded llmGatewayUrl and telemetryUrl from config; comment explains why they now live in urls.ts instead.
README.md	WORKOS_NO_PROMPT removed from environment variables table and legacy-compatibility notes updated to reference WORKOS_MODE=agent throughout.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["WORKOS_API_URL\n(env var, default: https://api.workos.com)"] --> B["getWorkOSApiUrl()\n(trailing slash removed)"]
    B --> C["getLlmGatewayUrl()\n= base + /llm-gateway"]
    B --> D["getTelemetryUrl()\n= base + /cli"]
    B --> E["Direct API calls"]
    F["WORKOS_DASHBOARD_URL"] --> G["getWorkOSDashboardUrl()"]
    H["WORKOS_AUTHKIT_DOMAIN"] --> I["getAuthkitDomain()"]
    subgraph "Interaction to Output coupling"
        J["WORKOS_MODE=agent"] --> K["resolveEffectiveOutputMode() forces json"]
        L["WORKOS_FORCE_TTY=1"] --> M["human output (overridden by agent mode)"]
    end

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A["WORKOS_API_URL\n(env var, default: https://api.workos.com)"] --> B["getWorkOSApiUrl()\n(trailing slash removed)"]
    B --> C["getLlmGatewayUrl()\n= base + /llm-gateway"]
    B --> D["getTelemetryUrl()\n= base + /cli"]
    B --> E["Direct API calls"]
    F["WORKOS_DASHBOARD_URL"] --> G["getWorkOSDashboardUrl()"]
    H["WORKOS_AUTHKIT_DOMAIN"] --> I["getAuthkitDomain()"]
    subgraph "Interaction to Output coupling"
        J["WORKOS_MODE=agent"] --> K["resolveEffectiveOutputMode() forces json"]
        L["WORKOS_FORCE_TTY=1"] --> M["human output (overridden by agent mode)"]
    end

Loading

_{Reviews (4): Last reviewed commit: "test: stop counting env writes as reads ..." | Re-trigger Greptile}