workos 0.10.1 → 0.11.1

package/README.md

@@ -51,10 +51,12 @@ workos [command]
 Commands:
   install                Install WorkOS AuthKit into your project
   auth                   Manage authentication (login, logout, status)
-  env                    Manage environment configurations
+  env                    Manage environment configurations (add, remove, switch, list, claim)
   doctor                 Diagnose WorkOS integration issues
   skills                 Manage WorkOS skills for coding agents (install, uninstall, list)
 
+Skills are automatically installed to detected coding agents when you run `workos install`. Use `workos skills list` to check status.
+
 Resource Management:
   organization (org)     Manage organizations
   user                   Manage users
@@ -85,6 +87,24 @@ Workflows:
 
 All management commands support `--json` for structured output (auto-enabled in non-TTY) and `--api-key` to override the active environment's key.
 
+### Unclaimed Environments
+
+When you run `workos install` without credentials, the CLI automatically provisions a temporary WorkOS environment — no account needed. This lets you try AuthKit immediately.
+
+```bash
+# Install with zero setup — environment provisioned automatically
+workos install
+
+# Check your environment
+workos env list
+# Shows: unclaimed (unclaimed) ← active
+
+# Claim the environment to link it to your WorkOS account
+workos env claim
+```
+
+Management commands work on unclaimed environments with a warning reminding you to claim.
+
 ### Workflows
 
 The compound workflow commands compose multiple API calls into common operations. These are the highest-value commands for both developers and AI agents.
@@ -483,7 +503,7 @@ OAuth credentials are stored in the system keychain (with `~/.workos/credentials
 ## How It Works
 
 1. **Detects** your framework and project structure
-2. **Prompts** for WorkOS credentials (API key masked)
+2. **Resolves credentials** — uses existing config, or auto-provisions an unclaimed environment if none found
 3. **Auto-configures** WorkOS dashboard (redirect URI, CORS, homepage URL)
 4. **Fetches** latest SDK documentation from workos.com
 5. **Uses AI** (Claude) to generate integration code

package/dist/bin.js

@@ -45,6 +45,12 @@ async function applyInsecureStorage(insecureStorage) {
         setInsecureConfigStorage(true);
     }
 }
+/** Show non-blocking warning if active env is unclaimed (once per session). */
+async function maybeWarnUnclaimed() {
+    const { warnIfUnclaimed } = await import('./lib/unclaimed-warning.js');
+    await warnIfUnclaimed();
+}
+import { resolveInstallCredentials } from './lib/resolve-install-credentials.js';
 /** Shared insecure-storage option for commands that access credentials */
 const insecureStorageOption = {
     'insecure-storage': {
@@ -53,20 +59,6 @@ const insecureStorageOption = {
         type: 'boolean',
     },
 };
-/**
- * Wrap a command handler with authentication check.
- * Ensures valid auth before executing the handler.
- * Respects --skip-auth flag for CI/testing.
- */
-function withAuth(handler) {
-    return async (argv) => {
-        const typedArgv = argv;
-        await applyInsecureStorage(typedArgv.insecureStorage);
-        if (!typedArgv.skipAuth)
-            await ensureAuthenticated();
-        await handler(argv);
-    };
-}
 const installerOptions = {
     direct: {
         alias: 'D',
@@ -173,6 +165,16 @@ yargs(rawArgs)
     default: false,
     describe: 'Output results as JSON (auto-enabled in non-TTY)',
     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', ''].includes(command))
+        return;
+    await applyInsecureStorage(argv.insecureStorage);
+    await maybeWarnUnclaimed();
 })
     .command('auth', 'Manage authentication (login, logout, status)', (yargs) => {
     yargs.options(insecureStorageOption);
@@ -319,6 +321,11 @@ yargs(rawArgs)
         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) => {
+        await applyInsecureStorage(argv.insecureStorage);
+        const { runClaim } = await import('./commands/claim.js');
+        await runClaim();
+    });
     return yargs.demandCommand(1, 'Please specify an env subcommand').strict();
 })
     .command(['organization', 'org'], 'Manage WorkOS organizations (create, update, get, list, delete)', (yargs) => {
@@ -1194,15 +1201,103 @@ yargs(rawArgs)
     const { runDebugSync } = await import('./commands/debug-sync.js');
     await runDebugSync(argv.directoryId, resolveApiKey({ apiKey: argv.apiKey }), resolveApiBaseUrl());
 })
-    .command('install', 'Install WorkOS AuthKit into your project (interactive framework detection and setup)', (yargs) => yargs.options(installerOptions), withAuth(async (argv) => {
+    // Alias — canonical command is `workos env claim`
+    .command('claim', 'Claim an unclaimed WorkOS environment (link it to your account)', (yargs) => yargs.options({
+    ...insecureStorageOption,
+}), async (argv) => {
+    await applyInsecureStorage(argv.insecureStorage);
+    const { runClaim } = await import('./commands/claim.js');
+    await runClaim();
+})
+    .command('install', 'Install WorkOS AuthKit into your project (interactive framework detection and setup)', (yargs) => yargs.options(installerOptions), async (argv) => {
+    await applyInsecureStorage(argv.insecureStorage);
+    await resolveInstallCredentials(argv.apiKey, argv.installDir, argv.skipAuth, ensureAuthenticated);
     const { handleInstall } = await import('./commands/install.js');
     await handleInstall(argv);
-}))
+})
+    .command('debug', false, (yargs) => {
+    yargs.options(insecureStorageOption);
+    registerSubcommand(yargs, 'state', 'Dump raw CLI state (credentials, config, storage)', (y) => y.option('show-secrets', {
+        type: 'boolean',
+        default: false,
+        describe: 'Show unredacted tokens and API keys',
+    }), async (argv) => {
+        await applyInsecureStorage(argv.insecureStorage);
+        const { runDebugState } = await import('./commands/debug.js');
+        await runDebugState({ showSecrets: argv.showSecrets });
+    });
+    registerSubcommand(yargs, 'reset', 'Clear auth state (keyring + files)', (y) => y
+        .option('force', {
+        type: 'boolean',
+        default: false,
+        describe: 'Skip confirmation prompt',
+    })
+        .option('credentials-only', {
+        type: 'boolean',
+        default: false,
+        describe: 'Only clear credentials',
+    })
+        .option('config-only', {
+        type: 'boolean',
+        default: false,
+        describe: 'Only clear config',
+    }), async (argv) => {
+        await applyInsecureStorage(argv.insecureStorage);
+        const { runDebugReset } = await import('./commands/debug.js');
+        await runDebugReset({
+            force: argv.force,
+            credentialsOnly: argv.credentialsOnly,
+            configOnly: argv.configOnly,
+        });
+    });
+    registerSubcommand(yargs, 'simulate', 'Simulate CLI states for testing', (y) => y
+        .option('expired-token', {
+        type: 'boolean',
+        default: false,
+        describe: 'Set token expiresAt to the past',
+    })
+        .option('no-keyring', {
+        type: 'boolean',
+        default: false,
+        describe: 'Force file-only storage mode',
+    })
+        .option('unclaimed', {
+        type: 'boolean',
+        default: false,
+        describe: 'Write synthetic unclaimed environment',
+    })
+        .option('no-auth', {
+        type: 'boolean',
+        default: false,
+        describe: 'Clear credentials, keep config',
+    }), async (argv) => {
+        await applyInsecureStorage(argv.insecureStorage);
+        const { runDebugSimulate } = await import('./commands/debug.js');
+        await runDebugSimulate({
+            expiredToken: argv.expiredToken,
+            noKeyring: argv.noKeyring,
+            unclaimed: argv.unclaimed,
+            noAuth: argv.noAuth,
+        });
+    });
+    registerSubcommand(yargs, 'env', 'Show WORKOS_* environment variables and their effects', (y) => y, async () => {
+        const { runDebugEnv } = await import('./commands/debug.js');
+        await runDebugEnv();
+    });
+    registerSubcommand(yargs, 'token', 'Decode and inspect the current access token', (y) => y, async (argv) => {
+        await applyInsecureStorage(argv.insecureStorage);
+        const { runDebugToken } = await import('./commands/debug.js');
+        await runDebugToken();
+    });
+    return yargs.demandCommand(1, 'Run "workos debug <command>" for debug tools.').strict();
+})
     .command('dashboard', false, // hidden from help
-(yargs) => yargs.options(installerOptions), withAuth(async (argv) => {
+(yargs) => yargs.options(installerOptions), async (argv) => {
+    await applyInsecureStorage(argv.insecureStorage);
+    await resolveInstallCredentials(argv.apiKey, argv.installDir, argv.skipAuth, ensureAuthenticated);
     const { handleInstall } = await import('./commands/install.js');
     await handleInstall({ ...argv, dashboard: true });
-}))
+})
     .command(['$0'], 'WorkOS AuthKit CLI', (yargs) => yargs.options(insecureStorageOption), async (argv) => {
     // Non-TTY: show help
     if (isNonInteractiveEnvironment()) {
@@ -1216,9 +1311,8 @@ yargs(rawArgs)
     if (clack.isCancel(shouldInstall) || !shouldInstall) {
         process.exit(0);
     }
-    // Auth check happens HERE, after user confirms
     await applyInsecureStorage(argv.insecureStorage);
-    await ensureAuthenticated();
+    await resolveInstallCredentials(undefined, undefined, false, ensureAuthenticated);
     const { handleInstall } = await import('./commands/install.js');
     await handleInstall({ ...argv, dashboard: false });
     process.exit(0);