workos 0.13.4 → 0.15.0

package/README.md

@@ -584,7 +584,18 @@ workos --help --json | jq '.commands[].name'
 
 ## Scripting & Automation
 
-The CLI auto-detects non-TTY environments (piped output, CI, coding agents) and switches to machine-friendly behavior. No flags required — just pipe it.
+The CLI separates **output mode** from **interaction mode**:
+
+- `--json` (or non-TTY auto-detection) controls **output formatting** only.
+- `--mode human|agent|ci` (or `WORKOS_MODE=...`) controls **interaction behavior** — prompts, browser launch, host trust, destructive confirmation.
+
+For coding agents, set both axes explicitly:
+
+```bash
+WORKOS_MODE=agent workos doctor --json --skip-ai
+```
+
+The CLI also auto-detects non-TTY environments (piped output, CI, coding agents) and falls back to machine-friendly defaults. No flags are required — just pipe it — but explicit mode is recommended for agents.
 
 ### JSON Output
 
@@ -605,6 +616,30 @@ workos org list 2>&1
 # → { "error": { "code": "no_api_key", "message": "No API key configured..." } }
 ```
 
+### Agent Mode
+
+When a coding agent drives the CLI, set agent mode explicitly so behavior is deterministic regardless of TTY:
+
+```bash
+WORKOS_MODE=agent workos doctor --json --skip-ai
+WORKOS_MODE=agent workos install --api-key ... --client-id ...
+```
+
+In agent mode the CLI:
+
+- Never prompts. Missing required arguments fail with structured errors instead of opening prompts.
+- Treats browser launch as best-effort. Auth flows always print the manual URL and code.
+- Probes host capabilities (home directory, keychain, browser launch). Host failures emit a `HOST_EXECUTION_UNTRUSTED` issue from `workos doctor` so agents can recognize sandboxed runs.
+- Requires explicit confirmation flags (e.g. `--yes`, `--force`) for destructive operations.
+
+In `ci` mode the CLI additionally refuses browser-based auth flows and prefers terse failures over recovery handoff text.
+
+Legacy compatibility:
+
+- `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.
+- Non-TTY without an explicit mode still defaults output to JSON and interaction to agent.
+
 ### Headless Installer
 
 In non-TTY, the installer streams progress as NDJSON (one JSON object per line):
@@ -632,8 +667,9 @@ 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_NO_PROMPT=1`     | Force non-interactive mode + JSON output                  |
-| `WORKOS_FORCE_TTY=1`     | Force interactive mode even when piped                    |
+| `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                                         |
 
 ### Command Discovery

package/dist/bin.js

@@ -19,20 +19,30 @@ 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.`);
     process.exit(1);
 }
-import { isNonInteractiveEnvironment } from './utils/environment.js';
-import { resolveOutputMode, setOutputMode, isJsonMode, outputJson, exitWithError } from './utils/output.js';
+import { InvalidInteractionModeError, isPromptAllowed, resolveInteractionMode, setInteractionMode, } from './utils/interaction-mode.js';
+import { resolveEffectiveOutputMode, resolveOutputMode, setOutputMode, isJsonMode, outputJson, exitWithError, } from './utils/output.js';
 import clack from './utils/clack.js';
 import { registerSubcommand } from './utils/register-subcommand.js';
 // Resolve output mode early from raw argv (before yargs parses)
 const rawArgs = hideBin(process.argv);
 const hasJsonFlag = rawArgs.includes('--json');
-setOutputMode(resolveOutputMode(hasJsonFlag));
+const baseOutputMode = resolveOutputMode(hasJsonFlag);
+setOutputMode(baseOutputMode);
+try {
+    const interaction = resolveInteractionMode({ argv: rawArgs });
+    setInteractionMode(interaction);
+    setOutputMode(resolveEffectiveOutputMode(baseOutputMode, interaction));
+}
+catch (error) {
+    if (error instanceof InvalidInteractionModeError) {
+        exitWithError({ code: 'invalid_mode', message: error.message });
+    }
+    throw error;
+}
 // Intercept --help --json before yargs parses (yargs exits on --help)
 if (hasJsonFlag && (rawArgs.includes('--help') || rawArgs.includes('-h'))) {
-    const { buildCommandTree } = await import('./utils/help-json.js');
-    const commandAliases = { org: 'organization' };
-    const rawCommand = rawArgs.find((a) => !a.startsWith('-'));
-    const command = rawCommand ? (commandAliases[rawCommand] ?? rawCommand) : undefined;
+    const { buildCommandTree, extractHelpJsonCommand } = await import('./utils/help-json.js');
+    const command = extractHelpJsonCommand(rawArgs);
     outputJson(buildCommandTree(command));
     process.exit(0);
 }
@@ -155,8 +165,8 @@ const installerOptions = {
         type: 'boolean',
     },
 };
-// Check for updates (blocks up to 500ms, skip in JSON mode to keep stdout clean)
-if (!isJsonMode())
+// Check for updates (blocks up to 500ms, skip in JSON/non-human modes to keep machine streams clean)
+if (!isJsonMode() && isPromptAllowed())
     await checkForUpdates();
 yargs(rawArgs)
     .parserConfiguration({ 'populate--': true })
@@ -166,13 +176,32 @@ yargs(rawArgs)
     default: false,
     describe: 'Output results as JSON (auto-enabled in non-TTY)',
     global: true,
+})
+    .option('mode', {
+    type: 'string',
+    choices: ['human', 'agent', 'ci'],
+    describe: 'Interaction mode: human, coding agent, or CI automation',
+    global: true,
 })
     .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.
     const command = String(argv._?.[0] ?? '');
-    if (['auth', 'skills', 'doctor', 'env', 'claim', 'install', 'debug', 'dashboard', 'emulate', 'dev', ''].includes(command))
+    if ([
+        'auth',
+        'skills',
+        'doctor',
+        'env',
+        'claim',
+        'install',
+        'debug',
+        'dashboard',
+        'emulate',
+        'dev',
+        'migrations',
+        '',
+    ].includes(command))
         return;
     await applyInsecureStorage(argv.insecureStorage);
     await maybeWarnUnclaimed();
@@ -312,7 +341,7 @@ yargs(rawArgs)
         await runEnvRemove(argv.name);
     });
     registerSubcommand(yargs, 'switch [name]', 'Switch active environment', (y) => y.positional('name', { type: 'string', describe: 'Environment name' }), async (argv) => {
-        if (!argv.name && isNonInteractiveEnvironment()) {
+        if (!argv.name && !isPromptAllowed()) {
             exitWithError({
                 code: 'missing_args',
                 message: 'Environment name required. Usage: workos env switch <name>',
@@ -333,6 +362,78 @@ yargs(rawArgs)
         await runClaim();
     });
     return yargs.demandCommand(1, 'Please specify an env subcommand').strict();
+})
+    .command('api [endpoint] [filter]', 'Make authenticated requests to the WorkOS API', (yargs) => yargs
+    .options(insecureStorageOption)
+    .positional('endpoint', {
+    type: 'string',
+    describe: "API endpoint path (e.g. /users), or 'ls' to list endpoints",
+})
+    .positional('filter', {
+    type: 'string',
+    describe: 'Filter keyword (used with ls)',
+})
+    .option('method', {
+    alias: 'X',
+    type: 'string',
+    describe: 'HTTP method (default: GET, or POST if body provided)',
+})
+    .option('data', {
+    alias: 'd',
+    type: 'string',
+    describe: 'JSON request body',
+})
+    .option('file', {
+    type: 'string',
+    describe: 'Read request body from a file (or - for stdin)',
+})
+    .option('include', {
+    alias: 'i',
+    type: 'boolean',
+    default: false,
+    describe: 'Show response headers',
+})
+    .option('api-key', {
+    type: 'string',
+    describe: 'Override the API key',
+})
+    .option('dry-run', {
+    type: 'boolean',
+    default: false,
+    describe: 'Show the request without executing it',
+})
+    .option('yes', {
+    alias: 'y',
+    type: 'boolean',
+    default: false,
+    describe: 'Skip confirmation for mutating requests',
+})
+    .example('workos api ls', 'List all available endpoints')
+    .example('workos api ls users', 'List endpoints matching "users"')
+    .example('workos api /user_management/users', 'GET /user_management/users')
+    .example('workos api /organizations -d \'{"name":"Acme"}\'', 'POST with a JSON body')
+    .example('workos api /organizations/org_123 -X DELETE', 'DELETE an organization'), async (argv) => {
+    await applyInsecureStorage(argv.insecureStorage);
+    const endpoint = argv.endpoint;
+    const filter = argv.filter;
+    const { runApiLs, runApiRequest, runApiInteractive } = await import('./commands/api/index.js');
+    if (!endpoint) {
+        await runApiInteractive({ apiKey: argv.apiKey });
+        return;
+    }
+    if (endpoint === 'ls') {
+        await runApiLs(filter);
+        return;
+    }
+    await runApiRequest(endpoint, {
+        method: argv.method,
+        data: argv.data,
+        file: argv.file,
+        include: argv.include,
+        apiKey: argv.apiKey,
+        dryRun: argv.dryRun,
+        yes: argv.yes,
+    });
 })
     .command(['organization', 'org'], 'Manage WorkOS organizations (create, update, get, list, delete)', (yargs) => {
     yargs.options({
@@ -1317,6 +1418,21 @@ yargs(rawArgs)
         await runDebugToken();
     });
     return yargs.demandCommand(1, 'Run "workos debug <command>" for debug tools.').strict();
+})
+    .command('migrations', 'Migrate users from identity providers (Auth0, Cognito, Clerk, Firebase) to WorkOS', (yargs) => yargs
+    .strictCommands(false)
+    .strict(false)
+    .help(false)
+    .version(false)
+    .options({
+    ...insecureStorageOption,
+    'api-key': { type: 'string', describe: 'WorkOS API key' },
+}), async (argv) => {
+    await applyInsecureStorage(argv.insecureStorage);
+    const { resolveApiKey } = await import('./lib/api-key.js');
+    const { getMigrationsPassthroughArgs, runMigrations } = await import('./commands/migrations.js');
+    const passthrough = getMigrationsPassthroughArgs(rawArgs);
+    await runMigrations(passthrough, resolveApiKey({ apiKey: argv.apiKey }));
 })
     .command('dashboard', false, // hidden from help
 (yargs) => yargs.options(installerOptions), async (argv) => {
@@ -1326,8 +1442,8 @@ yargs(rawArgs)
     await handleInstall({ ...argv, dashboard: true });
 })
     .command(['$0'], 'WorkOS AuthKit CLI', (yargs) => yargs.options(insecureStorageOption), async (argv) => {
-    // Non-TTY: show help
-    if (isNonInteractiveEnvironment()) {
+    // Non-human modes: show help instead of prompting
+    if (!isPromptAllowed()) {
         yargs(rawArgs).showHelp();
         return;
     }