feat(cua-cli): improve command descriptions for better clarity

Enhance help text throughout the CLI to make commands more discoverable
and their purposes clearer. Better descriptions help users understand
what each command does without consulting documentation.

Changes:
- Update main command descriptions:
  - 'cua auth': "Authenticate with CUA (login, logout, or export credentials)"
  - 'cua sb': "Create and manage cloud sandboxes (Linux, Windows, or macOS)"

- Improve auth subcommand descriptions:
  - login: "Authenticate via browser or API key and save credentials locally"
  - env: "Export your API key to a .env file in the current directory"
  - logout: "Clear stored API credentials from this machine"

- Enhance sandbox subcommand descriptions:
  - list: "List all your sandboxes with status and connection details"
  - create: "Provision a new cloud sandbox in your chosen OS, size, and region"
  - delete: "Permanently delete a sandbox and all its data"
  - start: "Start a stopped sandbox"
  - stop: "Stop a running sandbox (data is preserved)"
  - restart: "Restart a sandbox (reboot the system)"
  - vnc: "Open remote desktop (VNC) connection in your browser"

- Expand epilogue to show command hierarchy with examples
- Replace generic descriptions with action-oriented, specific language

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

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

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

@@ -8,11 +8,19 @@ export async function runCli() {
     .scriptName('cua')
     .usage('Usage: $0 <command> [options]')
     .epilogue(
-      'Grouped Commands (recommended):\n' +
-        '  cua auth <command>   Manage authentication (login, env, logout)\n' +
-        '  cua sb <command>     Manage sandboxes (list, create, start, stop, etc.)\n' +
+      'Recommended Command Structure:\n' +
+        '  cua auth <command>     Authenticate and manage credentials\n' +
+        '    login              Login via browser or with API key\n' +
+        '    env                Export API key to .env file\n' +
+        '    logout             Clear stored credentials\n' +
         '\n' +
-        'For more information: https://docs.cua.ai/libraries/cua-cli/commands'
+        '  cua sb <command>       Create and manage cloud sandboxes\n' +
+        '    list               View all your sandboxes\n' +
+        '    create             Provision a new sandbox\n' +
+        '    start/stop         Control sandbox state\n' +
+        '    vnc                Open remote desktop\n' +
+        '\n' +
+        'Documentation: https://docs.cua.ai/libraries/cua-cli/commands'
     );
   argv = registerAuthCommands(argv);
   argv = registerSandboxCommands(argv);

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

@@ -58,12 +58,12 @@ export function registerAuthCommands(y: Argv) {
   // Grouped structure: cua auth <command>
   y.command(
     'auth',
-    'Manage authentication',
+    'Authenticate with CUA (login, logout, or export credentials)',
     (y) => {
       return y
         .command(
           'login',
-          'Open browser to authorize and store API key',
+          'Authenticate via browser or API key and save credentials locally',
           (y) =>
             y.option('api-key', {
               type: 'string',
@@ -73,11 +73,11 @@ export function registerAuthCommands(y: Argv) {
         )
         .command(
           'env',
-          'Create or update .env with CUA_API_KEY (login if needed)',
+          'Export your API key to a .env file in the current directory',
           () => {},
           envHandler
         )
-        .command('logout', 'Remove stored API key', () => {}, logoutHandler)
+        .command('logout', 'Clear stored API credentials from this machine', () => {}, logoutHandler)
         .demandCommand(1, 'You must provide an auth command');
     },
     () => {}

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

@@ -306,12 +306,12 @@ export function registerSandboxCommands(y: Argv) {
   // Grouped structure: cua sandbox <command> or cua sb <command>
   y.command(
     ['sandbox', 'sb'],
-    'Manage sandboxes',
+    'Create and manage cloud sandboxes (Linux, Windows, or macOS)',
     (y) => {
       return y
         .command(
           ['list', 'ls', 'ps'],
-          'List sandboxes',
+          'List all your sandboxes with status and connection details',
           (y) =>
             y.option('show-passwords', {
               type: 'boolean',
@@ -322,7 +322,7 @@ export function registerSandboxCommands(y: Argv) {
         )
         .command(
           'create',
-          'Create a new sandbox',
+          'Provision a new cloud sandbox in your chosen OS, size, and region',
           (y) =>
             y
               .option('os', {
@@ -352,31 +352,31 @@ export function registerSandboxCommands(y: Argv) {
         )
         .command(
           'delete <name>',
-          'Delete a sandbox',
+          'Permanently delete a sandbox and all its data',
           (y) => y.positional('name', { type: 'string', describe: 'Sandbox name' }),
           deleteHandler
         )
         .command(
           'start <name>',
-          'Start a sandbox',
+          'Start a stopped sandbox',
           (y) => y.positional('name', { type: 'string', describe: 'Sandbox name' }),
           startHandler
         )
         .command(
           'stop <name>',
-          'Stop a sandbox',
+          'Stop a running sandbox (data is preserved)',
           (y) => y.positional('name', { type: 'string', describe: 'Sandbox name' }),
           stopHandler
         )
         .command(
           'restart <name>',
-          'Restart a sandbox',
+          'Restart a sandbox (reboot the system)',
           (y) => y.positional('name', { type: 'string', describe: 'Sandbox name' }),
           restartHandler
         )
         .command(
           ['vnc <name>', 'open <name>'],
-          'Open VNC desktop for a sandbox',
+          'Open remote desktop (VNC) connection in your browser',
           (y) => y.positional('name', { type: 'string', describe: 'Sandbox name' }),
           openHandler
         )