refactor: move claim to workos env claim subcommand (#93)

Claim is an environment lifecycle action, so it belongs under `env`
alongside add/remove/switch/list. Keeps a visible top-level alias
for discoverability.

Author: nicknisi

README.md

@@ -50,9 +50,8 @@ workos [command]
 
 Commands:
   install                Install WorkOS AuthKit into your project
-  claim                  Claim an unclaimed environment (link to your account)
   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)
 
@@ -99,7 +98,7 @@ workos env list
 # Shows: unclaimed (unclaimed) ← active
 
 # Claim the environment to link it to your WorkOS account
-workos claim
+workos env claim
 ```
 
 Management commands work on unclaimed environments with a warning reminding you to claim.

src/bin.ts

@@ -406,6 +406,17 @@ yargs(rawArgs)
         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) => {
@@ -2085,6 +2096,7 @@ yargs(rawArgs)
       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)',

src/commands/claim.ts

@@ -1,5 +1,5 @@
 /**
- * `workos claim` — claim an unclaimed environment.
+ * `workos env claim` — claim an unclaimed environment.
  *
  * Reads claim token from active environment, generates a nonce via
  * createClaimNonce(), opens browser to dashboard claim URL, and polls

src/commands/env.ts

@@ -233,6 +233,6 @@ export async function runEnvList(): Promise<void> {
 
   if (hasUnclaimed) {
     console.log('');
-    console.log(chalk.dim('  Run `workos claim` to keep this environment.'));
+    console.log(chalk.dim('  Run `workos env claim` to keep this environment.'));
   }
 }

src/lib/unclaimed-env-provision.ts

@@ -64,7 +64,7 @@ export async function tryProvisionUnclaimedEnv(options: UnclaimedEnvProvisionOpt
     config.activeEnvironment = 'unclaimed';
     saveConfig(config);
 
-    // Verify config persisted — critical for `workos claim` in a later process
+    // Verify config persisted — critical for `workos env claim` in a later process
     const readBack = getActiveEnvironment();
     if (!readBack || readBack.type !== 'unclaimed') {
       logError('[unclaimed-env-provision] Config read-back failed after save — claim token may not persist');
@@ -73,7 +73,7 @@ export async function tryProvisionUnclaimedEnv(options: UnclaimedEnvProvisionOpt
     }
 
     logInfo('[unclaimed-env-provision] Unclaimed environment provisioned and saved');
-    const inner = ` ✓ ${chalk.green('Environment provisioned')} — Run ${chalk.cyan('workos claim')} to keep it. `;
+    const inner = ` ✓ ${chalk.green('Environment provisioned')} — Run ${chalk.cyan('workos env claim')} to keep it. `;
     renderStderrBox(inner, chalk.green);
 
     return true;

src/lib/unclaimed-warning.ts

@@ -59,7 +59,7 @@ export async function warnIfUnclaimed(): Promise<void> {
     warningShownThisSession = true;
 
     if (!isJsonMode()) {
-      const inner = ` ${chalk.yellow('⚠ Unclaimed environment')} — Run ${chalk.cyan('workos claim')} to keep your data. `;
+      const inner = ` ${chalk.yellow('⚠ Unclaimed environment')} — Run ${chalk.cyan('workos env claim')} to keep your data. `;
       renderStderrBox(inner, chalk.yellow);
     }
   } catch (error) {

src/utils/help-json.ts

@@ -269,6 +269,20 @@ const commands: CommandSchema[] = [
         name: 'list',
         description: 'List all configured environments and show which is active',
       },
+      {
+        name: 'claim',
+        description: 'Claim an unclaimed WorkOS environment (link it to your account)',
+        options: [
+          {
+            name: 'json',
+            type: 'boolean',
+            description: 'Output in JSON format',
+            required: false,
+            default: false,
+            hidden: false,
+          },
+        ],
+      },
     ],
   },
   {
@@ -1034,21 +1048,6 @@ const commands: CommandSchema[] = [
       },
     ],
   },
-  {
-    name: 'claim',
-    description: 'Claim an unclaimed WorkOS environment (link it to your account)',
-    options: [
-      insecureStorageOpt,
-      {
-        name: 'json',
-        type: 'boolean',
-        description: 'Output in JSON format',
-        required: false,
-        default: false,
-        hidden: false,
-      },
-    ],
-  },
   // --- Workflow Commands ---
   {
     name: 'seed',