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 and renames the CLI's environment-variable surface: WORKOS_LLM_GATEWAY_URL and WORKOS_TELEMETRY_URL are removed in favour of deriving both paths from the single WORKOS_API_URL base; WORKOS_NO_PROMPT is removed in favour of WORKOS_MODE=agent; and INSTALLER_DEV/INSTALLER_DISABLE_PROXY are renamed to WORKOS_DEV/WORKOS_DISABLE_PROXY for prefix consistency.

• URL consolidation (src/utils/urls.ts): getLlmGatewayUrl() and getTelemetryUrl() now derive from getWorkOSApiUrl(), with trailing-slash normalization at the source; WORKOS_API_URL is the single override point for all three.
• Anti-drift guard (src/commands/env-var-catalog.spec.ts): new test scans src/ for dot-access process.env.WORKOS_* reads and fails if any are absent from ENV_VAR_CATALOG, preventing the catalog from silently drifting again.
• WORKOS_NO_PROMPT removal: cleanly removed from resolveInteractionMode, resolveOutputMode, InteractionModeSource, and all tests; agent JSON output is now governed exclusively by resolveEffectiveOutputMode.

Confidence Score: 4/5

Safe to merge after fixing the README table entry — one row still says WORKOS_API_BASE_URL where it should say WORKOS_API_URL, which would cause an agent or developer to set the wrong variable when trying to redirect the CLI's API calls.

The code changes are correct and well-tested throughout. The only concrete defect is the README environment-variables table listing WORKOS_API_BASE_URL rather than WORKOS_API_URL — the two variables have different purposes, and setting the wrong one silently does nothing. Every other change (URL derivation, WORKOS_NO_PROMPT removal, INSTALLER_* renames, anti-drift test) is consistent and complete.

README.md — the env-vars table in the Agent Interface section needs the WORKOS_API_BASE_URL row corrected to WORKOS_API_URL.

Important Files Changed

Filename	Overview
src/utils/urls.ts	Centralizes all WorkOS service endpoint resolution; WORKOS_API_URL is now the single base, with gateway and telemetry paths derived from it. Trailing-slash normalization is a nice defensive touch.
src/commands/env-var-catalog.spec.ts	New anti-drift guard that scans src/ for dot-access process.env.WORKOS_* reads and fails if any are missing from the catalog. Coverage gaps (bracket access, destructuring) are explicitly acknowledged in comments.
src/commands/debug.ts	ENV_VAR_CATALOG exported and expanded; removed WORKOS_NO_PROMPT, WORKOS_LLM_GATEWAY_URL, WORKOS_TELEMETRY_URL, and INSTALLER_* vars, and added missing entries (WORKOS_AGENT, WORKOS_SECRET_KEY, WORKOS_CLIENT_ID, doctor-check vars).
README.md	Removes WORKOS_NO_PROMPT from the agent env-vars table, but the unchanged WORKOS_API_BASE_URL row is misleading — the CLI reads WORKOS_API_URL to override its own API calls, while WORKOS_API_BASE_URL is only SET by workos dev for child processes.
src/utils/interaction-mode.ts	Removed workos_no_prompt source variant and the WORKOS_NO_PROMPT check from resolveInteractionMode; InteractionModeSource union type is now cleaner.
src/lib/agent-interface.ts	Renames INSTALLER_DISABLE_PROXY to WORKOS_DISABLE_PROXY and switches to the new getLlmGatewayUrl() from urls.ts; log message updated to match.
src/lib/settings.ts	Removed llmGatewayUrl and telemetryUrl from InstallerConfig and deleted the now-redundant getLlmGatewayUrl/getTelemetryUrl functions; both moved to urls.ts.
src/bin.ts	One-line rename of INSTALLER_DEV to WORKOS_DEV for the dotenv-loading condition.
src/utils/output.ts	Removes the WORKOS_NO_PROMPT branch from resolveOutputMode; agent-mode JSON forcing is now correctly delegated to resolveEffectiveOutputMode.
src/utils/analytics.ts	Import of getTelemetryUrl moved from settings.ts to urls.ts; no logic changes.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[WORKOS_API_URL env var] -->|strip trailing slash| B[getWorkOSApiUrl]
    B --> C["getLlmGatewayUrl\n(+/llm-gateway)"]
    B --> D["getTelemetryUrl\n(+/cli)"]
    B --> E[getWorkOSApiUrl — direct API calls]

    F[WORKOS_MODE env var] --> G[resolveInteractionMode]
    H[CI markers] --> G
    I[WORKOS_AGENT / IDE markers] --> G
    J[TTY detection] --> G
    G --> K{mode?}
    K -->|agent or ci| L["resolveEffectiveOutputMode\n→ json"]
    K -->|human| M["resolveEffectiveOutputMode\n→ human"]

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 env var] -->|strip trailing slash| B[getWorkOSApiUrl]
    B --> C["getLlmGatewayUrl\n(+/llm-gateway)"]
    B --> D["getTelemetryUrl\n(+/cli)"]
    B --> E[getWorkOSApiUrl — direct API calls]

    F[WORKOS_MODE env var] --> G[resolveInteractionMode]
    H[CI markers] --> G
    I[WORKOS_AGENT / IDE markers] --> G
    J[TTY detection] --> G
    G --> K{mode?}
    K -->|agent or ci| L["resolveEffectiveOutputMode\n→ json"]
    K -->|human| M["resolveEffectiveOutputMode\n→ human"]

Loading

_{Reviews (2): Last reviewed commit: "refactor: consolidate WorkOS URL resolut..." | Re-trigger Greptile}