feat!: consolidate and rename CLI environment variables (#180)

* feat!: consolidate and rename CLI environment variables

Reduce env-var sprawl in the CLI:

- Derive the LLM gateway and CLI telemetry URLs from WORKOS_API_URL
  instead of separate WORKOS_LLM_GATEWAY_URL / WORKOS_TELEMETRY_URL vars,
  so api.workos.com is no longer hardcoded in multiple places.
- Remove the redundant WORKOS_NO_PROMPT alias; WORKOS_MODE=agent is the
  single, self-documenting way to force agent interaction + JSON output.
- Standardize the INSTALLER_* prefix to WORKOS_* (WORKOS_DEV,
  WORKOS_DISABLE_PROXY).
- Fix the rotted `workos debug env` catalog (it was missing several vars)
  and add a test that scans src/ for WORKOS_* env reads and fails if any
  is missing from the catalog, preventing future drift.

BREAKING CHANGE: WORKOS_LLM_GATEWAY_URL and WORKOS_TELEMETRY_URL are
removed (derived from WORKOS_API_URL); WORKOS_NO_PROMPT is removed (use
WORKOS_MODE=agent); INSTALLER_DEV is renamed to WORKOS_DEV and
INSTALLER_DISABLE_PROXY to WORKOS_DISABLE_PROXY.

* refactor: consolidate WorkOS URL resolution into utils/urls.ts

Address code review on the env-var cleanup:

- Move getLlmGatewayUrl/getTelemetryUrl from settings.ts into urls.ts so the
  derived endpoints sit next to their base (getWorkOSApiUrl). This removes the
  backwards settings->urls import and makes urls.ts a dependency-free leaf that
  is the single home for WorkOS endpoint resolution. getAuthkitDomain stays in
  settings.ts since it's config-backed, not API-host-derived.
- Normalize the trailing slash once inside getWorkOSApiUrl instead of repeating
  the strip at each derivation site.
- Scope the env-var-catalog guard test's claim to dot-access reads and document
  the forms it doesn't cover (bracket access, destructuring).
- Fix a stale docstring on getCliAuthClientId (it is not env-overridable).

* test: simplify and strengthen the env-var catalog guard

- Replace the hand-rolled recursive file walk with fast-glob, the pattern
  already used across src/ (environment.ts, validator.ts, integrations).
- Read source files concurrently instead of in a sequential await loop.
- Make the catalog check bidirectional: it now also fails on stale entries
  (cataloged vars no longer read anywhere), not just missing ones, with an
  explicit CATALOG_ONLY escape hatch for any future non-dot-access reads.
  This subsumes the old WORKOS_-prefix assertion.

* chore: formatting

* test: stop counting env writes as reads in the catalog guard

WORKOS_SECRET_KEY is only written (migrations.ts sets it for the downstream
migrations SDK), never read by the CLI. The guard's regex matched the
assignment's left-hand side and "discovered" it, so it was catalogued as an
input credential — misleading, since the CLI ignores any user-provided value.

Tighten the discovery regex to exclude assignment targets (with an end-anchor
so the greedy capture can't backtrack to a truncated name), and drop the
write-only WORKOS_SECRET_KEY entry. The catalog now means exactly what its
docstring claims: WORKOS_ vars the CLI reads.

Author: nicknisi

DEVELOPMENT.md

@@ -114,9 +114,9 @@ Guidelines for new code:
 - For destructive operations, require an explicit `--yes`/`--force` flag whenever `!isPromptAllowed()` regardless of output mode.
 - For `auth_required` and other deterministic failures, attach recovery metadata via `src/utils/recovery-hints.ts` so agents can parse `error.recovery.hints[]`.
 
-Legacy compatibility — do not regress these:
+Mode resolution — do not regress these:
 
-- `WORKOS_NO_PROMPT=1` keeps mapping to agent interaction behavior **and** JSON output (legacy alias).
+- `WORKOS_MODE=agent` maps to agent interaction behavior **and** JSON output (via `resolveEffectiveOutputMode`). The old `WORKOS_NO_PROMPT` alias has been removed.
 - `WORKOS_FORCE_TTY=1` only affects output mode (forces human). It must not change interaction mode.
 - Non-TTY stdout still defaults output to JSON and interaction to agent.
 - `isNonInteractiveEnvironment()` from `src/utils/environment.ts` is a thin wrapper over `!isHumanMode()` kept for backward compatibility. Prefer the explicit interaction-mode predicates in new code.

README.md

@@ -663,10 +663,10 @@ In agent mode the CLI:
 
 In `ci` mode the CLI additionally refuses browser-based auth flows and prefers terse failures over recovery handoff text.
 
-Legacy compatibility:
+Mode resolution notes:
 
-- `WORKOS_NO_PROMPT=1` continues to work and is treated as agent interaction behavior plus JSON output.
-- `WORKOS_FORCE_TTY=1` continues to force human **output** mode but does not change interaction mode.
+- `WORKOS_MODE=agent` sets agent interaction behavior and forces JSON output. (This replaces the removed `WORKOS_NO_PROMPT` alias.)
+- `WORKOS_FORCE_TTY=1` forces human **output** mode but does not change interaction mode.
 - Non-TTY without an explicit mode still defaults output to JSON and interaction to agent.
 
 ### Headless Installer
@@ -697,7 +697,6 @@ workos install --api-key sk_test_xxx --client-id client_xxx --no-commit 2>/dev/n
 | `WORKOS_API_KEY`         | API key for management commands (bypasses stored config)  |
 | `WORKOS_API_BASE_URL`    | Override API base URL (set automatically by `workos dev`) |
 | `WORKOS_MODE`            | Interaction mode: `human`, `agent`, or `ci`               |
-| `WORKOS_NO_PROMPT=1`     | Legacy alias: agent interaction behavior + JSON output    |
 | `WORKOS_FORCE_TTY=1`     | Force human (non-JSON) **output** mode even when piped    |
 | `WORKOS_TELEMETRY=false` | Disable telemetry                                         |
 

src/bin-command-telemetry.integration.spec.ts

@@ -59,9 +59,11 @@ function runCli(args: string[], envOverrides: NodeJS.ProcessEnv = {}) {
     // silently produce no event and fail. Tests that exercise env precedence
     // override this explicitly via envOverrides.
     WORKOS_TELEMETRY: 'true',
-    // Unroutable URL: the flush fails, so the queued events are persisted to
-    // the pending file on exit where we can inspect the real payload.
-    WORKOS_TELEMETRY_URL: 'http://127.0.0.1:59999/cli',
+    // Unroutable API base: telemetry derives ${WORKOS_API_URL}/cli, so the
+    // flush fails and the queued events are persisted to the pending file on
+    // exit where we can inspect the real payload. (The tested commands fail
+    // validation / crash before any real API call, so this host is never hit.)
+    WORKOS_API_URL: 'http://127.0.0.1:59999',
     WORKOS_API_KEY: 'sk_dummy_for_test',
     ...envOverrides,
   };

src/bin.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // Load .env.local for local development when --local flag is used
-if (process.argv.includes('--local') || process.env.INSTALLER_DEV) {
+if (process.argv.includes('--local') || process.env.WORKOS_DEV) {
   const { config } = await import('dotenv');
   // bin.ts compiles to dist/bin.js, so go up one level to find .env.local
   const { fileURLToPath } = await import('node:url');

src/cli.config.ts

@@ -7,12 +7,12 @@ export const config = {
   model: 'claude-opus-4-5-20251101',
   doctorModel: 'claude-haiku-4-5-20251001',
 
-  // Production defaults - override via env vars for local dev
+  // Production defaults - override via env vars for local dev.
+  // The LLM gateway and CLI telemetry endpoints live under the WorkOS API
+  // host, so they're derived from WORKOS_API_URL rather than configured here.
   workos: {
     clientId: 'client_01KFKHSZWK9ADVJV854PDFQCCR',
     authkitDomain: 'https://signin.workos.com',
-    llmGatewayUrl: 'https://api.workos.com/llm-gateway',
-    telemetryUrl: 'https://api.workos.com/cli',
   },
 
   telemetry: {

src/commands/debug.spec.ts

@@ -593,16 +593,16 @@ describe('debug commands', () => {
 
     it('outputs valid JSON in json mode', async () => {
       jsonMode = true;
-      process.env.WORKOS_NO_PROMPT = '1';
+      process.env.WORKOS_DEBUG = '1';
 
       await runDebugEnv();
 
       const parsed = JSON.parse(consoleOutput[0]);
-      expect(parsed.variables.WORKOS_NO_PROMPT.value).toBe('1');
-      expect(parsed.set).toContain('WORKOS_NO_PROMPT');
-      expect(parsed.unset).not.toContain('WORKOS_NO_PROMPT');
+      expect(parsed.variables.WORKOS_DEBUG.value).toBe('1');
+      expect(parsed.set).toContain('WORKOS_DEBUG');
+      expect(parsed.unset).not.toContain('WORKOS_DEBUG');
 
-      delete process.env.WORKOS_NO_PROMPT;
+      delete process.env.WORKOS_DEBUG;
     });
 
     it('lists all known env vars', async () => {
@@ -614,7 +614,7 @@ describe('debug commands', () => {
       expect(Object.keys(parsed.variables)).toContain('WORKOS_API_KEY');
       expect(Object.keys(parsed.variables)).toContain('WORKOS_FORCE_TTY');
       expect(Object.keys(parsed.variables)).toContain('WORKOS_TELEMETRY');
-      expect(Object.keys(parsed.variables)).toContain('INSTALLER_DEV');
+      expect(Object.keys(parsed.variables)).toContain('WORKOS_DEV');
     });
   });
 });

src/commands/debug.ts

@@ -371,20 +371,36 @@ interface EnvVarInfo {
   effect: string;
 }
 
-const ENV_VAR_CATALOG: { name: string; effect: string }[] = [
-  { name: 'WORKOS_DEBUG', effect: 'Set to "1" to enable verbose debug logging for all commands' },
+/**
+ * Catalog of WORKOS_-prefixed environment variables the CLI reads.
+ *
+ * This is the single source of truth for `workos debug env`. A unit test
+ * (env-var-catalog.spec.ts) scans the source for `process.env.WORKOS_*` reads
+ * and fails if any are missing here, so this list can't silently drift.
+ */
+export const ENV_VAR_CATALOG: { name: string; effect: string }[] = [
+  // Credentials
   { name: 'WORKOS_API_KEY', effect: 'Bypasses credential resolution — used directly for API calls' },
+  { name: 'WORKOS_CLIENT_ID', effect: 'WorkOS client ID used during credential resolution' },
+  // Interaction & output
   { name: 'WORKOS_MODE', effect: 'Controls interaction behavior: human, agent, or CI' },
+  { name: 'WORKOS_AGENT', effect: 'Set to "1" to force agent interaction mode' },
   { name: 'WORKOS_FORCE_TTY', effect: 'Forces human (non-JSON) output mode, even when piped' },
-  { name: 'WORKOS_NO_PROMPT', effect: 'Legacy compatibility alias for agent interaction behavior and JSON output' },
+  { name: 'WORKOS_DEBUG', effect: 'Set to "1" to enable verbose debug logging for all commands' },
   { name: 'WORKOS_TELEMETRY', effect: 'Set to "false" to disable telemetry' },
-  { name: 'WORKOS_API_URL', effect: 'Overrides API base URL (default: https://api.workos.com)' },
+  // URLs (WORKOS_API_URL is the single base; gateway + telemetry derive from it)
+  {
+    name: 'WORKOS_API_URL',
+    effect: 'Overrides API base URL; also reroutes the LLM gateway and CLI telemetry endpoints',
+  },
   { name: 'WORKOS_DASHBOARD_URL', effect: 'Overrides dashboard URL (default: https://dashboard.workos.com)' },
   { name: 'WORKOS_AUTHKIT_DOMAIN', effect: 'Overrides AuthKit domain from settings' },
-  { name: 'WORKOS_LLM_GATEWAY_URL', effect: 'Overrides LLM gateway URL from settings' },
-  { name: 'WORKOS_TELEMETRY_URL', effect: 'Overrides CLI telemetry URL from settings' },
-  { name: 'INSTALLER_DEV', effect: 'Enables dev mode — loads .env.local at startup' },
-  { name: 'INSTALLER_DISABLE_PROXY', effect: 'Disables the credential proxy for gateway auth' },
+  { name: 'WORKOS_BASE_URL', effect: 'AuthKit base URL, read during doctor environment checks' },
+  { name: 'WORKOS_REDIRECT_URI', effect: 'OAuth redirect URI, read during doctor environment checks' },
+  { name: 'WORKOS_COOKIE_DOMAIN', effect: 'Session cookie domain, read during doctor environment checks' },
+  // Development
+  { name: 'WORKOS_DEV', effect: 'Enables dev mode — loads .env.local at startup' },
+  { name: 'WORKOS_DISABLE_PROXY', effect: 'Disables the credential proxy for gateway auth' },
 ];
 
 export async function runDebugEnv(): Promise<void> {

src/commands/env-var-catalog.spec.ts

@@ -0,0 +1,62 @@
+import { describe, it, expect } from 'vitest';
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import fg from 'fast-glob';
+import { ENV_VAR_CATALOG } from './debug.js';
+
+// Resolve the src/ root from this file's location (src/commands/*.spec.ts).
+const SRC_DIR = fileURLToPath(new URL('..', import.meta.url));
+
+// Matches dot-access env READS: `process.env.WORKOS_X` and the destructured
+// `env.WORKOS_X` form (e.g. interaction-mode.ts). Three guards, in order:
+//   - lookbehind `(?<![\w$])` excludes `projectEnv.WORKOS_X` / `sdkEnv.WORKOS_X`
+//   - `(?![A-Z0-9_])` anchors the end of the name so the greedy capture can't
+//     backtrack to a truncated match to satisfy the next lookahead
+//   - `(?!\s*=[^=])` excludes assignment targets (`process.env.WORKOS_X = ...`)
+//     so vars the CLI only *writes* for a downstream SDK aren't counted as reads;
+//     `===`/`!==` comparisons still match (it only rejects a lone `=`)
+//
+// Coverage is limited to dot access — it does NOT catch bracket access
+// (`process.env['WORKOS_X']`) or destructuring (`const { WORKOS_X } = process.env`).
+// No such reads exist today; if one is introduced, list it in CATALOG_ONLY below
+// so the bidirectional check still passes.
+const ENV_READ_PATTERN = /(?:process\.env|(?<![\w$])env)\.(WORKOS_[A-Z0-9_]+)(?![A-Z0-9_])(?!\s*=[^=])/g;
+
+// WORKOS_ vars that belong in the catalog but the scan can't see (non-dot-access
+// reads). Empty today — kept as the explicit escape hatch for the limitation above.
+const CATALOG_ONLY = new Set<string>();
+
+async function discoverEnvReads(): Promise<Set<string>> {
+  const files = await fg('**/*.ts', {
+    cwd: SRC_DIR,
+    absolute: true,
+    ignore: ['**/*.spec.ts', '**/*.d.ts'],
+  });
+  const contents = await Promise.all(files.map((file) => readFile(file, 'utf-8')));
+  const reads = new Set<string>();
+  for (const text of contents) {
+    for (const match of text.matchAll(ENV_READ_PATTERN)) reads.add(match[1]);
+  }
+  return reads;
+}
+
+describe('WORKOS_ env var catalog (debug env)', () => {
+  it('stays in sync with the WORKOS_ env vars the CLI reads (no missing or stale entries)', async () => {
+    const discovered = await discoverEnvReads();
+    const cataloged = new Set(ENV_VAR_CATALOG.map((v) => v.name));
+
+    const missing = [...discovered].filter((name) => !cataloged.has(name)).sort();
+    const stale = [...cataloged].filter((name) => !discovered.has(name) && !CATALOG_ONLY.has(name)).sort();
+
+    expect(missing, `Read in src/ but missing from ENV_VAR_CATALOG (debug.ts): ${missing.join(', ')}`).toEqual([]);
+    expect(
+      stale,
+      `In ENV_VAR_CATALOG (debug.ts) but no longer read in src/ — remove it, or add to CATALOG_ONLY if intentional: ${stale.join(', ')}`,
+    ).toEqual([]);
+  });
+
+  it('has no duplicate entries', () => {
+    const names = ENV_VAR_CATALOG.map((v) => v.name);
+    expect(new Set(names).size).toBe(names.length);
+  });
+});

src/doctor/checks/ai-analysis.ts

@@ -1,5 +1,6 @@
 import Anthropic from '@anthropic-ai/sdk';
-import { getLlmGatewayUrl, getAuthkitDomain, getCliAuthClientId, getConfig } from '../../lib/settings.js';
+import { getAuthkitDomain, getCliAuthClientId, getConfig } from '../../lib/settings.js';
+import { getLlmGatewayUrl } from '../../utils/urls.js';
 import { getCredentials, isTokenExpired, updateTokens, diagnoseCredentials } from '../../lib/credentials.js';
 import { refreshAccessToken } from '../../lib/token-refresh-client.js';
 import { buildDoctorPrompt, type AnalysisContext } from '../agent-prompt.js';

src/doctor/output.spec.ts

@@ -39,7 +39,6 @@ describe('doctor output', () => {
   it('formats interaction mode sources for human output', () => {
     expect(formatInteractionModeSource('flag')).toBe('--mode');
     expect(formatInteractionModeSource('env')).toBe('WORKOS_MODE');
-    expect(formatInteractionModeSource('workos_no_prompt')).toBe('WORKOS_NO_PROMPT');
     expect(formatInteractionModeSource('ci_env')).toBe('CI environment');
     expect(formatInteractionModeSource('agent_env')).toBe('agent environment');
     expect(formatInteractionModeSource('non_tty')).toBe('non-TTY');