Reorder CLI commands to show grouped structure first in help

- Register grouped commands (auth, sandbox/sb) first so they appear at top of help - Hide flat commands from help using describe: false while maintaining functionality - Fix remaining --configuration references in docs (should be --size) - Improves help clarity by showing recommended command structure prominently 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-12-20 12:29:50 -06:00 · 2025-11-18 13:48:07 +01:00
parent 27f6d448ea
commit 9c1fdcdac5
3 changed files with 101 additions and 111 deletions
--- a/docs/content/docs/libraries/cua-cli/commands.mdx
+++ b/docs/content/docs/libraries/cua-cli/commands.mdx
@@ -295,7 +295,7 @@ Invalid request or unsupported configuration
 ### 1. Use Descriptive Sandbox Names
 ```bash
 # Good
-cua create --os linux --configuration small --region north-america
+cua create --os linux --size small --region north-america
 # Then rename or use meaningful names in the dashboard

 # Better workflow
@@ -321,7 +321,7 @@ alias prod-sandbox="cua vnc my-production-sandbox"
 ### 4. Monitoring Provisioning
 ```bash
 # For sandboxes that need provisioning time
-cua create --os windows --configuration large --region europe
+cua create --os windows --size large --region europe
 # Sandbox provisioning started: my-sandbox-abc123
 # Job ID: job-xyz789

--- a/libs/typescript/cua-cli/src/commands/auth.ts
+++ b/libs/typescript/cua-cli/src/commands/auth.ts
@@ -28,34 +28,7 @@ const logoutHandler = async (_argv: Record<string, unknown>) => {
 };

 export function registerAuthCommands(y: Argv) {
-  // Flat structure (backwards compatible, hidden from help)
-  y.command({
-    command: 'login',
-    describe: 'Open browser to authorize and store API key',
-    hidden: true,
-    builder: (y: Argv) =>
-      y.option('api-key', {
-        type: 'string',
-        describe: 'API key to store directly',
-      }),
-    handler: loginHandler,
-  } as any)
-    .command({
-      command: 'env',
-      describe: 'Create or update .env with CUA_API_KEY (login if needed)',
-      hidden: true,
-      builder: (y: Argv) => y,
-      handler: envHandler,
-    } as any)
-    .command({
-      command: 'logout',
-      describe: 'Remove stored API key',
-      hidden: true,
-      builder: (y: Argv) => y,
-      handler: logoutHandler,
-    } as any);
-
-  // Grouped structure: cua auth <command>
+  // Grouped structure: cua auth <command> (register first to appear first in help)
  y.command(
    'auth',
    'Authenticate with CUA (login, logout, or export credentials)',
@@ -83,5 +56,29 @@ export function registerAuthCommands(y: Argv) {
    () => {}
  );

+  // Flat structure (backwards compatible, hidden from help)
+  y.command({
+    command: 'login',
+    describe: false as any, // Hide from help
+    builder: (y: Argv) =>
+      y.option('api-key', {
+        type: 'string',
+        describe: 'API key to store directly',
+      }),
+    handler: loginHandler,
+  } as any)
+    .command({
+      command: 'env',
+      describe: false as any, // Hide from help
+      builder: (y: Argv) => y,
+      handler: envHandler,
+    } as any)
+    .command({
+      command: 'logout',
+      describe: false as any, // Hide from help
+      builder: (y: Argv) => y,
+      handler: logoutHandler,
+    } as any);
+
  return y;
 }
--- a/libs/typescript/cua-cli/src/commands/sandbox.ts
+++ b/libs/typescript/cua-cli/src/commands/sandbox.ts
@@ -223,87 +223,7 @@ const openHandler = async (argv: Record<string, unknown>) => {

 // Register commands in both flat and grouped structures
 export function registerSandboxCommands(y: Argv) {
-  // Flat structure (backwards compatible, hidden from help)
-  y.command({
-    command: ['list', 'ls', 'ps'],
-    describe: 'List sandboxes',
-    hidden: true,
-    builder: (y: Argv) =>
-      y.option('show-passwords', {
-        type: 'boolean',
-        default: false,
-        describe: 'Show sandbox passwords in output',
-      }),
-    handler: listHandler,
-  } as any)
-    .command({
-      command: 'create',
-      describe: 'Create a new sandbox',
-      hidden: true,
-      builder: (y: Argv) =>
-        y
-          .option('os', {
-            type: 'string',
-            choices: ['linux', 'windows', 'macos'],
-            demandOption: true,
-            describe: 'Operating system',
-          })
-          .option('size', {
-            type: 'string',
-            choices: ['small', 'medium', 'large'],
-            demandOption: true,
-            describe: 'Sandbox size',
-          })
-          .option('region', {
-            type: 'string',
-            choices: [
-              'north-america',
-              'europe',
-              'asia-pacific',
-              'south-america',
-            ],
-            demandOption: true,
-            describe: 'Sandbox region',
-          }),
-      handler: createHandler,
-    } as any)
-    .command({
-      command: 'delete <name>',
-      describe: 'Delete a sandbox',
-      hidden: true,
-      builder: (y: Argv) => y.positional('name', { type: 'string', describe: 'Sandbox name' }),
-      handler: deleteHandler,
-    } as any)
-    .command({
-      command: 'start <name>',
-      describe: 'Start a sandbox',
-      hidden: true,
-      builder: (y: Argv) => y.positional('name', { type: 'string', describe: 'Sandbox name' }),
-      handler: startHandler,
-    } as any)
-    .command({
-      command: 'stop <name>',
-      describe: 'Stop a sandbox',
-      hidden: true,
-      builder: (y: Argv) => y.positional('name', { type: 'string', describe: 'Sandbox name' }),
-      handler: stopHandler,
-    } as any)
-    .command({
-      command: 'restart <name>',
-      describe: 'Restart a sandbox',
-      hidden: true,
-      builder: (y: Argv) => y.positional('name', { type: 'string', describe: 'Sandbox name' }),
-      handler: restartHandler,
-    } as any)
-    .command({
-      command: ['vnc <name>', 'open <name>'],
-      describe: 'Open VNC desktop for a sandbox',
-      hidden: true,
-      builder: (y: Argv) => y.positional('name', { type: 'string', describe: 'Sandbox name' }),
-      handler: openHandler,
-    } as any);
-
-  // Grouped structure: cua sandbox <command> or cua sb <command>
+  // Grouped structure: cua sandbox <command> or cua sb <command> (register first to appear first in help)
  y.command(
    ['sandbox', 'sb'],
    'Create and manage cloud sandboxes (Linux, Windows, or macOS)',
@@ -385,5 +305,78 @@ export function registerSandboxCommands(y: Argv) {
    () => {}
  );

+  // Flat structure (backwards compatible, hidden from help)
+  y.command({
+    command: ['list', 'ls', 'ps'],
+    describe: false as any, // Hide from help
+    builder: (y: Argv) =>
+      y.option('show-passwords', {
+        type: 'boolean',
+        default: false,
+        describe: 'Show sandbox passwords in output',
+      }),
+    handler: listHandler,
+  } as any)
+    .command({
+      command: 'create',
+      describe: false as any, // Hide from help
+      builder: (y: Argv) =>
+        y
+          .option('os', {
+            type: 'string',
+            choices: ['linux', 'windows', 'macos'],
+            demandOption: true,
+            describe: 'Operating system',
+          })
+          .option('size', {
+            type: 'string',
+            choices: ['small', 'medium', 'large'],
+            demandOption: true,
+            describe: 'Sandbox size',
+          })
+          .option('region', {
+            type: 'string',
+            choices: [
+              'north-america',
+              'europe',
+              'asia-pacific',
+              'south-america',
+            ],
+            demandOption: true,
+            describe: 'Sandbox region',
+          }),
+      handler: createHandler,
+    } as any)
+    .command({
+      command: 'delete <name>',
+      describe: false as any, // Hide from help
+      builder: (y: Argv) => y.positional('name', { type: 'string', describe: 'Sandbox name' }),
+      handler: deleteHandler,
+    } as any)
+    .command({
+      command: 'start <name>',
+      describe: false as any, // Hide from help
+      builder: (y: Argv) => y.positional('name', { type: 'string', describe: 'Sandbox name' }),
+      handler: startHandler,
+    } as any)
+    .command({
+      command: 'stop <name>',
+      describe: false as any, // Hide from help
+      builder: (y: Argv) => y.positional('name', { type: 'string', describe: 'Sandbox name' }),
+      handler: stopHandler,
+    } as any)
+    .command({
+      command: 'restart <name>',
+      describe: false as any, // Hide from help
+      builder: (y: Argv) => y.positional('name', { type: 'string', describe: 'Sandbox name' }),
+      handler: restartHandler,
+    } as any)
+    .command({
+      command: ['vnc <name>', 'open <name>'],
+      describe: false as any, // Hide from help
+      builder: (y: Argv) => y.positional('name', { type: 'string', describe: 'Sandbox name' }),
+      handler: openHandler,
+    } as any);
+
  return y;
 }