feat: add environment management commands and config store

Add `workos env` command group (add/remove/switch/list) for managing
multiple environments with API keys. Introduces a keyring-backed
config store (with file fallback) separate from OAuth credentials,
and an API key resolution utility for upcoming management commands.

Author: nicknisi

src/bin.ts

@@ -31,11 +31,13 @@ if (!satisfies(process.version, NODE_VERSION_RANGE)) {
 import { isNonInteractiveEnvironment } from './utils/environment.js';
 import clack from './utils/clack.js';
 
-/** Apply insecure storage flag if set */
+/** Apply insecure storage flag if set (for both credential-store and config-store) */
 async function applyInsecureStorage(insecureStorage?: boolean): Promise<void> {
   if (insecureStorage) {
     const { setInsecureStorage } = await import('./lib/credentials.js');
+    const { setInsecureConfigStorage } = await import('./lib/config-store.js');
     setInsecureStorage(true);
+    setInsecureConfigStorage(true);
   }
 }
 
@@ -223,6 +225,60 @@ yargs(hideBin(process.argv))
       await handleDoctor(argv);
     },
   )
+  .command('env', 'Manage environment configurations', (yargs) =>
+    yargs
+      .options(insecureStorageOption)
+      .command(
+        'add [name] [apiKey]',
+        'Add an environment configuration',
+        (yargs) =>
+          yargs
+            .positional('name', { type: 'string', describe: 'Environment name' })
+            .positional('apiKey', { type: 'string', describe: 'WorkOS API key' })
+            .option('endpoint', { type: 'string', describe: 'Custom API endpoint' }),
+        async (argv) => {
+          await applyInsecureStorage(argv.insecureStorage);
+          const { runEnvAdd } = await import('./commands/env.js');
+          await runEnvAdd({
+            name: argv.name,
+            apiKey: argv.apiKey,
+            endpoint: argv.endpoint,
+          });
+        },
+      )
+      .command(
+        'remove <name>',
+        'Remove an environment configuration',
+        (yargs) => yargs.positional('name', { type: 'string', demandOption: true, describe: 'Environment name' }),
+        async (argv) => {
+          await applyInsecureStorage(argv.insecureStorage);
+          const { runEnvRemove } = await import('./commands/env.js');
+          await runEnvRemove(argv.name);
+        },
+      )
+      .command(
+        'switch [name]',
+        'Switch active environment',
+        (yargs) => yargs.positional('name', { type: 'string', describe: 'Environment name' }),
+        async (argv) => {
+          await applyInsecureStorage(argv.insecureStorage);
+          const { runEnvSwitch } = await import('./commands/env.js');
+          await runEnvSwitch(argv.name);
+        },
+      )
+      .command(
+        'list',
+        'List configured environments',
+        {},
+        async (argv) => {
+          await applyInsecureStorage((argv as any).insecureStorage);
+          const { runEnvList } = await import('./commands/env.js');
+          await runEnvList();
+        },
+      )
+      .demandCommand(1, 'Please specify an env subcommand')
+      .strict(),
+  )
   .command(
     'install',
     'Install WorkOS AuthKit into your project',

src/commands/env.spec.ts

@@ -0,0 +1,163 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { mkdtempSync, rmdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+// Mock debug utilities
+vi.mock('../utils/debug.js', () => ({
+  logWarn: vi.fn(),
+}));
+
+// Mock clack prompts
+vi.mock('../utils/clack.js', () => ({
+  default: {
+    log: {
+      success: vi.fn(),
+      error: vi.fn(),
+      info: vi.fn(),
+      step: vi.fn(),
+    },
+    text: vi.fn(),
+    select: vi.fn(),
+    password: vi.fn(),
+    isCancel: vi.fn(() => false),
+  },
+}));
+
+let testDir: string;
+
+vi.mock('node:os', async (importOriginal) => {
+  const original = await importOriginal<typeof import('node:os')>();
+  return {
+    ...original,
+    default: {
+      ...original,
+      homedir: () => testDir,
+    },
+    homedir: () => testDir,
+  };
+});
+
+const { getConfig, saveConfig, setInsecureConfigStorage, clearConfig } = await import('../lib/config-store.js');
+const { runEnvAdd, runEnvRemove, runEnvSwitch, runEnvList } = await import('./env.js');
+const clack = (await import('../utils/clack.js')).default;
+
+// Spy on process.exit
+const mockExit = vi.spyOn(process, 'exit').mockImplementation((() => {
+  throw new Error('process.exit called');
+}) as any);
+
+describe('env commands', () => {
+  beforeEach(() => {
+    testDir = mkdtempSync(join(tmpdir(), 'env-cmd-test-'));
+    setInsecureConfigStorage(true);
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    clearConfig();
+    try {
+      rmdirSync(join(testDir, '.workos'), { recursive: true });
+    } catch {}
+    try {
+      rmdirSync(testDir);
+    } catch {}
+  });
+
+  describe('runEnvAdd (non-interactive)', () => {
+    it('adds an environment with provided args', async () => {
+      await runEnvAdd({ name: 'prod', apiKey: 'sk_live_abc123' });
+      const config = getConfig();
+      expect(config?.environments.prod).toBeDefined();
+      expect(config?.environments.prod.apiKey).toBe('sk_live_abc123');
+      expect(config?.environments.prod.type).toBe('production');
+    });
+
+    it('detects sandbox type from sk_test_ prefix', async () => {
+      await runEnvAdd({ name: 'sandbox', apiKey: 'sk_test_abc123' });
+      const config = getConfig();
+      expect(config?.environments.sandbox.type).toBe('sandbox');
+    });
+
+    it('stores endpoint when provided', async () => {
+      await runEnvAdd({ name: 'local', apiKey: 'sk_test_abc', endpoint: 'http://localhost:8001' });
+      const config = getConfig();
+      expect(config?.environments.local.endpoint).toBe('http://localhost:8001');
+    });
+
+    it('auto-sets active environment on first add', async () => {
+      await runEnvAdd({ name: 'prod', apiKey: 'sk_live_abc' });
+      const config = getConfig();
+      expect(config?.activeEnvironment).toBe('prod');
+    });
+
+    it('does not change active environment on subsequent adds', async () => {
+      await runEnvAdd({ name: 'prod', apiKey: 'sk_live_abc' });
+      await runEnvAdd({ name: 'sandbox', apiKey: 'sk_test_abc' });
+      const config = getConfig();
+      expect(config?.activeEnvironment).toBe('prod');
+    });
+
+    it('rejects invalid environment name', async () => {
+      await expect(runEnvAdd({ name: 'INVALID NAME', apiKey: 'sk_test' })).rejects.toThrow('process.exit');
+    });
+  });
+
+  describe('runEnvRemove', () => {
+    it('removes an existing environment', async () => {
+      await runEnvAdd({ name: 'prod', apiKey: 'sk_live_abc' });
+      await runEnvRemove('prod');
+      const config = getConfig();
+      expect(config?.environments.prod).toBeUndefined();
+    });
+
+    it('switches active env when removing the active one', async () => {
+      await runEnvAdd({ name: 'prod', apiKey: 'sk_live_abc' });
+      await runEnvAdd({ name: 'sandbox', apiKey: 'sk_test_abc' });
+      // prod is active (first added)
+      await runEnvRemove('prod');
+      const config = getConfig();
+      expect(config?.activeEnvironment).toBe('sandbox');
+    });
+
+    it('errors for non-existent environment', async () => {
+      await runEnvAdd({ name: 'prod', apiKey: 'sk_live_abc' });
+      await expect(runEnvRemove('missing')).rejects.toThrow('process.exit');
+    });
+
+    it('errors when no environments configured', async () => {
+      await expect(runEnvRemove('anything')).rejects.toThrow('process.exit');
+    });
+  });
+
+  describe('runEnvSwitch', () => {
+    it('switches to a named environment', async () => {
+      await runEnvAdd({ name: 'prod', apiKey: 'sk_live_abc' });
+      await runEnvAdd({ name: 'sandbox', apiKey: 'sk_test_abc' });
+      await runEnvSwitch('sandbox');
+      const config = getConfig();
+      expect(config?.activeEnvironment).toBe('sandbox');
+    });
+
+    it('errors for non-existent environment', async () => {
+      await runEnvAdd({ name: 'prod', apiKey: 'sk_live_abc' });
+      await expect(runEnvSwitch('missing')).rejects.toThrow('process.exit');
+    });
+
+    it('errors when no environments configured', async () => {
+      await expect(runEnvSwitch('anything')).rejects.toThrow('process.exit');
+    });
+  });
+
+  describe('runEnvList', () => {
+    it('shows info message when no environments', async () => {
+      await runEnvList();
+      expect(clack.log.info).toHaveBeenCalledWith(expect.stringContaining('No environments configured'));
+    });
+
+    it('does not throw when environments exist', async () => {
+      await runEnvAdd({ name: 'prod', apiKey: 'sk_live_abc' });
+      await expect(runEnvList()).resolves.not.toThrow();
+    });
+  });
+});