workos 0.17.1 → 0.19.0

package/README.md

@@ -85,6 +85,9 @@ Resource Management:
 Migrations:
   migrations             Migrate users and SSO connections into WorkOS
 
+Local Development:
+  emulate                Start a local WorkOS API emulator
+
 Workflows:
   seed                   Declarative resource provisioning from YAML
   setup-org              One-shot organization onboarding
@@ -221,38 +224,9 @@ workos migrations import --csv users.csv
 
 Run `workos migrations --help` for all available subcommands.
 
-<!-- UNRELEASED: Local Development (emulator) — hidden until beta testing is complete.
-     To restore, uncomment this section and re-enable the `emulate` and `dev` commands
-     in src/bin.ts and src/utils/help-json.ts.
-
-### Local Development
-
-Test your WorkOS integration locally without hitting the live API. The emulator provides a full in-memory WorkOS API replacement with all major endpoints.
-
-#### `workos dev` — One command to start everything
-
-The fastest way to develop locally. Starts the emulator and your app together, auto-detecting your framework and injecting the right environment variables.
-
-```bash
-# Auto-detects framework (Next.js, Vite, Remix, SvelteKit, etc.) and dev command
-workos dev
-
-# Override the dev command
-workos dev -- npx vite --port 5173
-
-# Custom emulator port and seed data
-workos dev --port 8080 --seed workos-emulate.config.yaml
-```
-
-Your app receives these environment variables automatically:
+### Local Emulation
 
-- `WORKOS_API_BASE_URL` — points to the local emulator (e.g. `http://localhost:4100`)
-- `WORKOS_API_KEY` — `sk_test_default`
-- `WORKOS_CLIENT_ID` — `client_emulate`
-
-#### `workos emulate` — Standalone emulator
-
-Run the emulator on its own for CI, test suites, or when you want manual control.
+Start a local WorkOS API emulator. The command is backed by [`@workos/emulate`](https://github.com/workos/emulate); the standalone package binary is `workos-emulate`.
 
 ```bash
 # Start with defaults (port 4100)
@@ -260,124 +234,13 @@ workos emulate
 
 # CI-friendly: JSON output, custom port
 workos emulate --port 9100 --json
-# → {"url":"http://localhost:9100","port":9100,"apiKey":"sk_test_default","health":"http://localhost:9100/health"}
 
 # Pre-load seed data
 workos emulate --seed workos-emulate.config.yaml
-```
 
-The emulator supports `GET /health` for readiness polling and shuts down cleanly on Ctrl+C.
-
-#### Seed configuration
-
-Create a `workos-emulate.config.yaml` (auto-detected) or pass `--seed <path>`:
-
-```yaml
-users:
-  - email: alice@acme.com
-    first_name: Alice
-    password: test123
-    email_verified: true
-
-organizations:
-  - name: Acme Corp
-    domains:
-      - domain: acme.com
-        state: verified
-    memberships:
-      - user_id: <user_id>
-        role: admin
-
-connections:
-  - name: Acme SSO
-    organization: Acme Corp
-    connection_type: GenericSAML
-    domains: [acme.com]
-
-roles:
-  - slug: admin
-    name: Admin
-    permissions: [posts:read, posts:write]
-
-permissions:
-  - slug: posts:read
-    name: Read Posts
-  - slug: posts:write
-    name: Write Posts
-
-webhookEndpoints:
-  - url: http://localhost:3000/webhooks
-    events: [user.created, organization.updated]
-```
-
-#### Programmatic API
-
-Use the emulator directly in test suites without the CLI:
-
-```typescript
-import { createEmulator } from 'workos/emulate';
-
-const emulator = await createEmulator({
-  port: 0, // random available port
-  seed: {
-    users: [{ email: 'test@example.com', password: 'secret' }],
-  },
-});
-
-// Use emulator.url as your WORKOS_API_BASE_URL
-const res = await fetch(`${emulator.url}/user_management/users`, {
-  headers: { Authorization: 'Bearer sk_test_default' },
-});
-
-// Reset between tests (clears data, re-applies seed)
-emulator.reset();
-
-// Clean up
-await emulator.close();
-```
-
-#### Emulated endpoints
-
-The emulator covers the full WorkOS API surface (~84% of OpenAPI spec endpoints). Run `pnpm check:coverage <openapi-spec>` to see exact coverage.
-
-| Endpoint Group           | Routes                                                                                                                                                                 |
-| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Organizations            | CRUD, external_id lookup, domain management                                                                                                                            |
-| Users                    | CRUD, email uniqueness, password management                                                                                                                            |
-| Organization memberships | CRUD, role assignment, deactivate/reactivate                                                                                                                           |
-| Organization domains     | CRUD, verification                                                                                                                                                     |
-| SSO connections          | CRUD, domain-based lookup                                                                                                                                              |
-| SSO flow                 | Authorize, token exchange, profile, JWKS, SSO logout                                                                                                                   |
-| AuthKit                  | OAuth authorize (login_hint, multi-user), authenticate (7 grant types incl. refresh_token, MFA TOTP, org selection, device code), PKCE, sealed sessions, impersonation |
-| Sessions                 | List, revoke, logout redirect, JWKS per client                                                                                                                         |
-| Email verification       | Send code, confirm                                                                                                                                                     |
-| Password reset           | Create token, confirm                                                                                                                                                  |
-| Magic auth               | Create code                                                                                                                                                            |
-| Auth factors             | TOTP enrollment, delete                                                                                                                                                |
-| MFA challenges           | Create challenge, verify code                                                                                                                                          |
-| Invitations              | CRUD, accept, revoke, resend, get by token                                                                                                                             |
-| Config                   | Redirect URIs, CORS origins, JWT template                                                                                                                              |
-| User features            | Authorized apps, connected accounts, data providers                                                                                                                    |
-| Widgets                  | Token generation                                                                                                                                                       |
-| Authorization (RBAC)     | Environment roles, org roles (priority ordering), permissions, role-permission management                                                                              |
-| Authorization (FGA)      | Resources CRUD, permission checks, role assignments                                                                                                                    |
-| Directory Sync           | List/get/delete directories, users, groups                                                                                                                             |
-| Audit Logs               | Actions, schemas, events, exports, org config/retention                                                                                                                |
-| Feature Flags            | List/get, enable/disable, targets, org/user evaluations                                                                                                                |
-| Connect                  | Applications CRUD, client secrets                                                                                                                                      |
-| Data Integrations        | OAuth authorize + token exchange                                                                                                                                       |
-| Radar                    | Attempts list/get, allow/deny lists                                                                                                                                    |
-| API Keys                 | Validate, delete, list by org                                                                                                                                          |
-| Portal                   | Generate admin portal links                                                                                                                                            |
-| Legacy MFA               | Enroll/get/delete factors, challenge/verify                                                                                                                            |
-| Webhook Endpoints        | CRUD with auto-generated secrets, secret masking                                                                                                                       |
-| Events                   | Paginated event stream with type filtering                                                                                                                             |
-| Event Bus                | Auto-emits events on entity CRUD via collection hooks, fire-and-forget webhook delivery with HMAC signatures                                                           |
-| Pipes                    | Connection CRUD, mock `getAccessToken()`                                                                                                                               |
-
-JWT tokens include `role` and `permissions` claims for org-scoped sessions. All list endpoints support cursor pagination (`before`, `after`, `limit`, `order`). Error responses match the WorkOS format (`{ message, code, errors }`).
-
-END UNRELEASED -->
+# Show login pages for SSO/AuthKit browser testing
+workos emulate --interactive
+```
 
 ### Environment Management
 
@@ -663,10 +526,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 +560,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                                         |
 

package/dist/bin.js

@@ -1,6 +1,6 @@
 #!/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');
@@ -14,7 +14,7 @@ import { hideBin } from 'yargs/helpers';
 import { ensureAuthenticated } from './lib/ensure-auth.js';
 import { checkForUpdates } from './lib/version-check.js';
 const NODE_VERSION_RANGE = getConfig().nodeVersion;
-// Have to run this above the other imports because they are importing clack that
+// Have to run this above the other imports because they are importing the UI facade that
 // has the problematic imports.
 if (!satisfies(process.version, NODE_VERSION_RANGE)) {
     red(`WorkOS AuthKit installer requires Node.js ${NODE_VERSION_RANGE}. You are using Node.js ${process.version}. Please upgrade your Node.js version.`);
@@ -22,7 +22,7 @@ if (!satisfies(process.version, NODE_VERSION_RANGE)) {
 }
 import { InvalidInteractionModeError, isPromptAllowed, resolveInteractionMode, setInteractionMode, } from './utils/interaction-mode.js';
 import { resolveEffectiveOutputMode, resolveOutputMode, setOutputMode, isJsonMode, outputJson, outputError, exitWithError, } from './utils/output.js';
-import clack from './utils/clack.js';
+import ui, { PromptUnavailableError } from './utils/ui.js';
 import { registerSubcommand } from './utils/register-subcommand.js';
 import { installCrashReporter, sanitizeMessage } from './utils/crash-reporter.js';
 import { installStoreForward, recoverPendingEvents } from './utils/telemetry-store-forward.js';
@@ -34,6 +34,8 @@ import { CliExit } from './utils/cli-exit.js';
 import { telemetryClient } from './utils/telemetry-client.js';
 import { ExitCode } from './utils/exit-codes.js';
 import { analytics } from './utils/analytics.js';
+import { formatWorkOSCommand, getWorkOSCommand } from './utils/command-invocation.js';
+import { MIGRATIONS_DESCRIPTION } from './lib/constants.js';
 // Enable debug logging for all commands via env var.
 // Subsumes the installer's --debug flag for non-installer commands.
 if (process.env.WORKOS_DEBUG === '1') {
@@ -208,6 +210,11 @@ const installerOptions = {
         choices: ['npm', 'pnpm', 'yarn', 'bun'],
         type: 'string',
     },
+    router: {
+        choices: ['app', 'pages'],
+        describe: 'Next.js router to target when detection is ambiguous (app or pages)',
+        type: 'string',
+    },
 };
 // Check for updates (blocks up to 500ms, skip in JSON/non-human modes to keep machine streams clean)
 if (!isJsonMode() && isPromptAllowed())
@@ -267,8 +274,9 @@ async function runCli() {
     })
         .middleware(async (argv) => {
         // Warn about unclaimed environments before management commands.
-        // Excluded: auth/claim/install/dashboard handle their own credential flows;
-        // skills/doctor/env/debug are utility commands where the warning is unnecessary.
+        // Excluded: auth/claim/install/setup/dashboard handle their own credential
+        // or onboarding flows; skills/doctor/env/debug are utility commands where
+        // the warning is unnecessary.
         const command = String(argv._?.[0] ?? '');
         if ([
             'auth',
@@ -277,6 +285,7 @@ async function runCli() {
             'env',
             'claim',
             'install',
+            'setup',
             'debug',
             'dashboard',
             'emulate',
@@ -373,6 +382,31 @@ async function runCli() {
             });
         });
         return yargs.demandCommand(1, 'Please specify a skills subcommand').strict();
+    })
+        .command('mcp', 'Manage the WorkOS MCP server in coding agents (Claude Code, Codex, Cursor)', (yargs) => {
+        registerSubcommand(yargs, 'install', 'Add the WorkOS MCP server to detected coding agents', (y) => y.option('agent', {
+            alias: 'a',
+            type: 'array',
+            string: true,
+            description: 'Target specific agent(s): claude-code, codex, cursor',
+        }), async (argv) => {
+            const { runMcpInstall } = await import('./commands/mcp.js');
+            await runMcpInstall({ agent: argv.agent });
+        });
+        registerSubcommand(yargs, 'remove', 'Remove the WorkOS MCP server from coding agents', (y) => y.option('agent', {
+            alias: 'a',
+            type: 'array',
+            string: true,
+            description: 'Target specific agent(s): claude-code, codex, cursor',
+        }), async (argv) => {
+            const { runMcpRemove } = await import('./commands/mcp.js');
+            await runMcpRemove({ agent: argv.agent });
+        });
+        registerSubcommand(yargs, 'status', 'Show which coding agents have the WorkOS MCP server configured', (y) => y, async () => {
+            const { runMcpStatus } = await import('./commands/mcp.js');
+            await runMcpStatus();
+        });
+        return yargs.demandCommand(1, 'Please specify an mcp subcommand').strict();
     })
         .command('doctor', 'Diagnose WorkOS AuthKit integration issues in the current project', (yargs) => yargs.options({
         verbose: {
@@ -413,6 +447,38 @@ async function runCli() {
     }), async (argv) => {
         const { handleDoctor } = await import('./commands/doctor.js');
         await handleDoctor(argv);
+    })
+        .command('verify-login', 'Verify the AuthKit login loop end-to-end against the active environment (creates and deletes a throwaway user)', (yargs) => yargs.options({
+        ...insecureStorageOption,
+        'api-key': {
+            type: 'string',
+            describe: 'WorkOS API key (overrides environment config). Format: sk_test_* (production keys are refused)',
+        },
+        'client-id': {
+            type: 'string',
+            describe: 'WorkOS client ID (overrides the active environment)',
+        },
+        method: {
+            type: 'string',
+            choices: ['password'],
+            default: 'password',
+            describe: 'Authentication method to verify',
+        },
+    }), async (argv) => {
+        await applyInsecureStorage(argv.insecureStorage);
+        const { resolveApiKey, resolveApiBaseUrl } = await import('./lib/api-key.js');
+        const { getActiveEnvironment } = await import('./lib/config-store.js');
+        const { runVerifyLogin } = await import('./commands/verify-login.js');
+        const apiKey = resolveApiKey({ apiKey: argv.apiKey }); // exits 4 if none
+        const activeEnv = getActiveEnvironment();
+        await runVerifyLogin({
+            apiKey,
+            clientId: argv.clientId ?? activeEnv?.clientId,
+            baseUrl: resolveApiBaseUrl(),
+            envType: activeEnv?.type ?? null,
+            envName: activeEnv?.name,
+            method: argv.method,
+        });
     })
         // NOTE: When adding commands here, also update src/utils/help-json.ts
         .command('env', 'Manage environment configurations (API keys, endpoints, active environment)', (yargs) => {
@@ -431,7 +497,7 @@ async function runCli() {
                 endpoint: argv.endpoint,
             });
         });
-        registerSubcommand(yargs, 'remove <name>', 'Remove an environment configuration', (y) => y.positional('name', { type: 'string', demandOption: true, describe: 'Environment name' }), async (argv) => {
+        registerSubcommand(yargs, 'remove <name>', 'Remove an environment from local CLI config (does not delete or unclaim the environment in WorkOS)', (y) => y.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);
@@ -440,7 +506,7 @@ async function runCli() {
             if (!argv.name && !isPromptAllowed()) {
                 exitWithError({
                     code: 'missing_args',
-                    message: 'Environment name required. Usage: workos env switch <name>',
+                    message: `Environment name required. Usage: ${formatWorkOSCommand('env switch <name>')}`,
                 });
             }
             await applyInsecureStorage(argv.insecureStorage);
@@ -452,11 +518,16 @@ async function runCli() {
             const { runEnvList } = await import('./commands/env.js');
             await runEnvList();
         });
-        registerSubcommand(yargs, 'claim', 'Claim an unclaimed environment (link it to your account)', (y) => y, async (argv) => {
+        registerSubcommand(yargs, 'claim', 'Claim an unclaimed environment — link it to your account (permanent — cannot be undone)', (y) => y, async (argv) => {
             await applyInsecureStorage(argv.insecureStorage);
             const { runClaim } = await import('./commands/claim.js');
             await runClaim();
         });
+        registerSubcommand(yargs, 'provision', 'Provision a new unclaimed WorkOS environment (credentials only, no code changes)', (y) => y, async (argv) => {
+            await applyInsecureStorage(argv.insecureStorage);
+            const { runEnvProvision } = await import('./commands/env.js');
+            await runEnvProvision();
+        });
         return yargs.demandCommand(1, 'Please specify an env subcommand').strict();
     })
         .command('api [endpoint] [filter]', 'Make authenticated requests to the WorkOS API', (yargs) => yargs
@@ -1396,6 +1467,30 @@ async function runCli() {
         const { resolveApiKey, resolveApiBaseUrl } = await import('./lib/api-key.js');
         const { runSeed } = await import('./commands/seed.js');
         await runSeed({ file: argv.file, clean: argv.clean, init: argv.init }, resolveApiKey({ apiKey: argv.apiKey }), resolveApiBaseUrl());
+    })
+        .command('setup', 'Set up your coding agent (install WorkOS skills + MCP server)', (yargs) => yargs.options({
+        ...insecureStorageOption,
+        agents: { type: 'string', describe: 'Comma-separated agent keys (claude-code, codex, cursor, goose)' },
+        'skills-only': { type: 'boolean', describe: 'Install skills only (skip the MCP server)' },
+        'mcp-only': { type: 'boolean', describe: 'Install the MCP server only (skip skills)' },
+        yes: { type: 'boolean', alias: 'y', describe: 'Install without prompting' },
+        reset: { type: 'boolean', describe: 'Re-enable automatic setup offers after a decline' },
+    }), async (argv) => {
+        await applyInsecureStorage(argv.insecureStorage);
+        const { runSetup } = await import('./commands/setup.js');
+        await runSetup({
+            trigger: 'command',
+            agents: argv.agents
+                ? String(argv.agents)
+                    .split(',')
+                    .map((a) => a.trim())
+                    .filter(Boolean)
+                : undefined,
+            skillsOnly: argv.skillsOnly,
+            mcpOnly: argv.mcpOnly,
+            assumeYes: argv.yes,
+            reset: argv.reset,
+        });
     })
         .command('setup-org <name>', 'One-shot organization onboarding (create org, domain, roles, portal link)', (yargs) => yargs.positional('name', { type: 'string', demandOption: true, describe: 'Organization name' }).options({
         ...insecureStorageOption,
@@ -1439,7 +1534,7 @@ async function runCli() {
         await runDebugSync(argv.directoryId, resolveApiKey({ apiKey: argv.apiKey }), resolveApiBaseUrl());
     })
         // Alias — canonical command is `workos env claim`
-        .command('claim', 'Claim an unclaimed WorkOS environment (link it to your account)', (yargs) => yargs.options({
+        .command('claim', 'Claim an unclaimed WorkOS environment — link it to your account (permanent — cannot be undone)', (yargs) => yargs.options({
         ...insecureStorageOption,
     }), async (argv) => {
         await applyInsecureStorage(argv.insecureStorage);
@@ -1451,14 +1546,6 @@ async function runCli() {
         await resolveInstallCredentials(argv.apiKey, argv.installDir, argv.skipAuth, ensureAuthenticated);
         const { handleInstall } = await import('./commands/install.js');
         await handleInstall(argv);
-    })
-        .command('emulate', false, // Hidden: unreleased beta feature
-    (yargs) => yargs.options({
-        port: { type: 'number', default: 4100, describe: 'Port to listen on' },
-        seed: { type: 'string', describe: 'Path to seed config file (YAML or JSON)' },
-    }), async (argv) => {
-        const { runEmulate } = await import('./commands/emulate.js');
-        await runEmulate({ port: argv.port, seed: argv.seed, json: argv.json });
     })
         .command('dev', false, // Hidden: unreleased beta feature
     (yargs) => yargs.options({
@@ -1471,6 +1558,33 @@ async function runCli() {
             seed: argv.seed,
             '--': argv['--'],
         });
+    })
+        .command('emulate', 'Start a local WorkOS API emulator', (yargs) => yargs.options({
+        port: {
+            alias: 'p',
+            type: 'number',
+            default: 4100,
+            describe: 'Port to listen on',
+        },
+        seed: {
+            alias: 's',
+            type: 'string',
+            describe: 'Path to seed config file (YAML or JSON)',
+        },
+        interactive: {
+            alias: 'i',
+            type: 'boolean',
+            default: false,
+            describe: 'Show login pages for SSO/AuthKit',
+        },
+    }), async (argv) => {
+        const { runEmulate } = await import('./commands/emulate.js');
+        await runEmulate({
+            port: argv.port,
+            seed: argv.seed,
+            json: argv.json,
+            interactive: argv.interactive,
+        });
     })
         .command('debug', false, (yargs) => {
         yargs.options(insecureStorageOption);
@@ -1552,9 +1666,9 @@ async function runCli() {
             const { runDebugToken } = await import('./commands/debug.js');
             await runDebugToken();
         });
-        return yargs.demandCommand(1, 'Run "workos debug <command>" for debug tools.').strict();
+        return yargs.demandCommand(1, `Run "${getWorkOSCommand()} debug <command>" for debug tools.`).strict();
     })
-        .command('migrations', 'Migrate users from identity providers (Auth0, Cognito, Clerk, Firebase) to WorkOS', (yargs) => yargs
+        .command('migrations', MIGRATIONS_DESCRIPTION, (yargs) => yargs
         .strictCommands(false)
         .strict(false)
         .help(false)
@@ -1579,16 +1693,23 @@ async function runCli() {
         await handleInstall({ ...argv, dashboard: true });
     })
         .command(['$0'], 'WorkOS AuthKit CLI', (yargs) => yargs.options(insecureStorageOption), async (argv) => {
-        // Non-human modes: show help instead of prompting
+        // Non-human modes: emit machine-readable command tree (JSON) or the
+        // fully-configured parser help (human non-TTY edge) instead of prompting.
         if (!isPromptAllowed()) {
-            yargs(rawArgs).showHelp();
+            if (isJsonMode()) {
+                const { buildCommandTree } = await import('./utils/help-json.js');
+                outputJson(buildCommandTree());
+            }
+            else {
+                parser.showHelp();
+            }
             return;
         }
         // TTY: ask if user wants to run installer
-        const shouldInstall = await clack.confirm({
+        const shouldInstall = await ui.confirm({
             message: 'Run the AuthKit installer?',
         });
-        if (clack.isCancel(shouldInstall) || !shouldInstall) {
+        if (ui.isCancel(shouldInstall) || !shouldInstall) {
             return;
         }
         await applyInsecureStorage(argv.insecureStorage);
@@ -1628,6 +1749,17 @@ async function runCli() {
                 },
             };
         }
+        else if (error instanceof PromptUnavailableError) {
+            // A prompt was attempted where the user can't answer (--json, or non-TTY
+            // stdin) on a direct command. Not a crash — surface a clear, structured
+            // error with its own code so scripts and telemetry can distinguish it.
+            process.exitCode = 1;
+            commandOutcome = {
+                success: false,
+                options: { flags, reason: 'validation_error', errorCode: 'prompt_unavailable' },
+            };
+            outputError({ code: 'prompt_unavailable', message: error.message });
+        }
         else {
             // Unexpected error (crash)
             process.exitCode = 1;