feat(cua-cli): add grouped auth commands and update docs to prefer verbose style

Add support for grouped auth command structure (cua auth login/env/logout)
while maintaining backwards compatibility with flat commands (cua login/env/logout).
Update all documentation to prefer the more explicit grouped style.

Changes:
- Refactor auth.ts to support both flat and grouped command structures
- Extract auth command handlers for reuse (loginHandler, envHandler, logoutHandler)
- Add "cua auth" command group with login/env/logout subcommands
- Update quickstart to use "cua auth login" instead of "cua login"
- Update CLI index.mdx and installation.mdx to use grouped style
- Update commands.mdx to show grouped style as primary with flat as alternative
- Update README.md to document both command styles
- Update error messages and examples to use grouped style

Both command styles work identically - users can choose based on preference.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

libs/typescript/cua-cli/README.md

@@ -17,10 +17,26 @@ bun run ./index.ts -- --help
 ## Commands
 
 - **Auth**
-  - `cua login` – opens browser to authorize; stores API key locally
-  - `cua login --api-key sk-...` – stores provided key directly
-  - `cua env` – writes/updates `.env` with `CUA_API_KEY`
-  - `cua logout` – clears stored API key
+
+  The CLI supports both **flat** and **grouped** command styles:
+
+  ```bash
+  # Grouped style (explicit)
+  cua auth login
+  cua auth env
+  cua auth logout
+
+  # Flat style (quick)
+  cua login
+  cua env
+  cua logout
+  ```
+
+  **Available Commands:**
+  - `login` – opens browser to authorize; stores API key locally
+    - `--api-key sk-...` – stores provided key directly
+  - `env` – writes/updates `.env` with `CUA_API_KEY`
+  - `logout` – clears stored API key
 
 - **Sandboxes**
 

libs/typescript/cua-cli/src/commands/auth.ts

@@ -3,45 +3,77 @@ import { ensureApiKeyInteractive, loginViaBrowser } from '../auth';
 import { writeEnvFile } from '../util';
 import type { Argv } from 'yargs';
 
+// Command handlers
+const loginHandler = async (argv: Record<string, unknown>) => {
+  if (argv['api-key']) {
+    setApiKey(String(argv['api-key']));
+    console.log('API key saved');
+    return;
+  }
+  console.log('Opening browser for CLI auth...');
+  const token = await loginViaBrowser();
+  setApiKey(token);
+  console.log('API key saved');
+};
+
+const envHandler = async (_argv: Record<string, unknown>) => {
+  const token = await ensureApiKeyInteractive();
+  const out = await writeEnvFile(process.cwd(), token);
+  console.log(`Wrote ${out}`);
+};
+
+const logoutHandler = async (_argv: Record<string, unknown>) => {
+  clearApiKey();
+  console.log('Logged out');
+};
+
 export function registerAuthCommands(y: Argv) {
-  return y
-    .command(
-      'login',
-      'Open browser to authorize and store API key',
-      (y) =>
-        y.option('api-key', {
-          type: 'string',
-          describe: 'API key to store directly',
-        }),
-      async (argv: Record<string, unknown>) => {
-        if (argv['api-key']) {
-          setApiKey(String(argv['api-key']));
-          console.log('API key saved');
-          return;
-        }
-        console.log('Opening browser for CLI auth...');
-        const token = await loginViaBrowser();
-        setApiKey(token);
-        console.log('API key saved');
-      }
-    )
+  // Flat structure (backwards compatible)
+  y.command(
+    'login',
+    'Open browser to authorize and store API key',
+    (y) =>
+      y.option('api-key', {
+        type: 'string',
+        describe: 'API key to store directly',
+      }),
+    loginHandler
+  )
     .command(
       'env',
       'Create or update .env with CUA_API_KEY (login if needed)',
       () => {},
-      async (_argv: Record<string, unknown>) => {
-        const token = await ensureApiKeyInteractive();
-        const out = await writeEnvFile(process.cwd(), token);
-        console.log(`Wrote ${out}`);
-      }
+      envHandler
     )
-    .command(
-      'logout',
-      'Remove stored API key',
-      () => {},
-      async (_argv: Record<string, unknown>) => {
-        clearApiKey();
-        console.log('Logged out');
-      }
-    );
+    .command('logout', 'Remove stored API key', () => {}, logoutHandler);
+
+  // Grouped structure: cua auth <command>
+  y.command(
+    'auth',
+    'Manage authentication',
+    (y) => {
+      return y
+        .command(
+          'login',
+          'Open browser to authorize and store API key',
+          (y) =>
+            y.option('api-key', {
+              type: 'string',
+              describe: 'API key to store directly',
+            }),
+          loginHandler
+        )
+        .command(
+          'env',
+          'Create or update .env with CUA_API_KEY (login if needed)',
+          () => {},
+          envHandler
+        )
+        .command('logout', 'Remove stored API key', () => {}, logoutHandler)
+        .demandCommand(1, 'You must provide an auth command');
+    },
+    () => {}
+  );
+
+  return y;
 }