@aifabrix/builder 2.43.0 → 2.44.0

package/lib/cli/setup-app.help.js

@@ -0,0 +1,67 @@
+/**
+ * @fileoverview Help text blocks for app-level CLI commands.
+ */
+
+'use strict';
+
+const TEST_HELP_AFTER = `
+Examples:
+  # External system (integration/<systemKey>/) — local validation
+  $ aifabrix test hubspot
+  $ aifabrix test hubspot -v
+  $ aifabrix test hubspot -d
+
+  # Builder app (builder/<app>/) — runs in container
+  $ aifabrix test myapp -e dev
+  $ aifabrix test myapp -e tst
+
+Notes:
+  - To run unit test for one datasource, use:
+      aifabrix datasource test <datasourceKey>
+  - To run integration test, use:
+      aifabrix test-integration <app>
+  - Option --sync is not supported here (local validation only); use upload or dataplane test commands with --sync.
+`;
+
+const TEST_INTEGRATION_HELP_AFTER = `
+Examples:
+  # External system (integration/<systemKey>/) — integration health across datasources via dataplane
+  $ aifabrix test-integration hubspot
+  $ aifabrix test-integration hubspot -v
+  $ aifabrix test-integration hubspot -d
+
+  # Builder app (builder/<app>/) — runs in container
+  $ aifabrix test-integration myapp -e dev
+  $ aifabrix test-integration myapp -e tst
+
+Notes:
+  - To run integration test for one datasource, use:
+      aifabrix datasource test-integration <datasourceKey>
+  - To run E2E test, use:
+      aifabrix test-e2e <app>
+  - Optional --sync publishes local files to the dataplane first (external integration under integration/<systemKey>/ only).
+`;
+
+const TEST_E2E_HELP_AFTER = `
+Examples:
+  # External system (integration/<systemKey>/) — E2E across datasources via dataplane
+  $ aifabrix test-e2e hubspot
+  $ aifabrix test-e2e hubspot -v
+  $ aifabrix test-e2e hubspot -d
+
+  # Builder app (builder/<app>/) — runs in container
+  $ aifabrix test-e2e myapp -e dev
+  $ aifabrix test-e2e myapp -e tst
+
+Notes:
+  - To run E2E for one datasource, use:
+      aifabrix datasource test-e2e <datasourceKey>
+  - Optional --sync publishes local files to the dataplane first (external integration only).
+`;
+
+module.exports = {
+  TEST_HELP_AFTER,
+  TEST_INTEGRATION_HELP_AFTER,
+  TEST_E2E_HELP_AFTER
+};
+

package/lib/cli/setup-app.js

@@ -1,3 +1,4 @@
+const { formatSuccessParagraph } = require('../utils/cli-test-layout-chalk');
 /**
  * CLI application lifecycle command setup (create, wizard, build, run, push, deploy, dockerfile).
  *
@@ -11,6 +12,24 @@ const path = require('path');
 const app = require('../app');
 const logger = require('../utils/logger');
 const { handleCommandError } = require('../utils/cli-utils');
+const { setupInstallTestE2eLintCommands } = require('./setup-app.test-commands');
+
+const CREATE_HELP_AFTER = `
+Examples:
+  $ aifabrix create myapi --type webapp -l typescript
+  $ aifabrix create mycrm --wizard
+`;
+
+const DEPLOY_HELP_AFTER = `
+Examples:
+  $ aifabrix deploy myapp
+  $ aifabrix deploy myext --local
+`;
+
+const PUSH_HELP_AFTER = `
+Example:
+  $ aifabrix push myapp -t v1.0.0
+`;
 
 /**
  * Normalize options for external system creation
@@ -102,7 +121,8 @@ async function handleCreateCommand(appName, options) {
 
 function setupCreateCommand(program) {
   program.command('create <app>')
-    .description('Create new application with configuration files')
+    .description('Scaffold builder or external app (flags or --wizard)')
+    .addHelpText('after', CREATE_HELP_AFTER)
     .option('-p, --port <port>', 'Application port', '3000')
     .option('-d, --database', 'Requires database')
     .option('-r, --redis', 'Requires Redis')
@@ -142,15 +162,15 @@ Examples:
   $ aifabrix wizard --config wizard.yaml  Run headless from a wizard config file
   $ aifabrix wizard hubspot-test --debug  Enable debug output and save debug manifests on validation failure
 
-Config path: When appName is provided, integration/<appName>/wizard.yaml is used for load/save and error.log.
+Config path: When appName is provided, integration/<systemKey>/wizard.yaml is used for load/save and error.log.
 To change settings after a run, edit that file and run "aifabrix wizard <app>" again.
 Headless config must include: appName, mode (create-system|add-datasource), source (type + filePath/url/platform).
 See integration/hubspot-test/wizard-hubspot-e2e.yaml for an example.`;
   program.command('wizard [appName]')
-    .description('Create or extend external systems (OpenAPI, MCP, or known platforms like HubSpot) via guided steps or a config file')
+    .description('Guided external system setup (OpenAPI, MCP, HubSpot, …) or headless wizard.yaml')
     .option('-a, --app <app>', 'Application name (synonym for positional appName)')
     .option('--config <file>', 'Run headless using a wizard.yaml file (appName, mode, source, credential, preferences)')
-    .option('--silent', 'Run with saved integration/<app>/wizard.yaml only; no prompts (requires app name and existing wizard.yaml)')
+    .option('--silent', 'Run with saved integration/<systemKey>/wizard.yaml only; no prompts (requires app name and existing wizard.yaml)')
     .option('--debug', 'Enable debug output and save debug manifests on validation failure')
     .addHelpText('after', wizardHelp)
     .action(async(positionalAppName, options) => {
@@ -172,9 +192,10 @@ In dev: use --reload for sync and mount (requires remote server with Mutagen, or
 Examples:
   $ aifabrix run myapp
   $ aifabrix run myapp --env tst
+  $ aifabrix run myapp --tag v1.0.0
   $ aifabrix run myapp --reload`;
   program.command('run <app>')
-    .description('Run application locally (or remotely on your Docker host)')
+    .description('Run app locally or on remote Docker host')
     .option('-p, --port <port>', 'Override local port')
     .option('-d, --debug', 'Enable debug output with detailed container information')
     .option('-t, --tag <tag>', 'Image tag to run (e.g. v1.0.0); overrides application.yaml image.tag')
@@ -193,14 +214,15 @@ Examples:
 
 function setupBuildRunLogsDownCommands(program) {
   program.command('build <app>')
-    .description('Build container image (auto-detects runtime)')
+    .description('Build Docker image (auto-detect runtime)')
     .option('-l, --language <lang>', 'Override language detection')
     .option('-f, --force-template', 'Force rebuild from template')
+    .option('--no-cache', 'Full Docker rebuild (disable layer cache); use after Dockerfile or context fixes')
     .option('-t, --tag <tag>', 'Image tag (default: latest). Set image.tag in application.yaml to match for deploy.')
     .action(async(appName, options) => {
       try {
         const imageTag = await app.buildApp(appName, options);
-        logger.log(`✅ Built image: ${imageTag}`);
+        logger.log(`✔ Built image: ${imageTag}`);
       } catch (error) {
         handleCommandError(error, 'build');
         process.exit(1);
@@ -210,7 +232,7 @@ function setupBuildRunLogsDownCommands(program) {
   registerRunCommand(program);
 
   program.command('logs <app>')
-    .description('Show application container logs (and optional env summary with secrets masked)')
+    .description('Tail app container logs (optional env summary; secrets masked)')
     .option('-f', 'Follow log stream')
     .option('-t, --tail <lines>', 'Number of lines (default: 100); 0 = full list', '100')
     .option('-l, --level <level>', 'Show only logs at this level or above (debug|info|warn|error)')
@@ -227,7 +249,7 @@ function setupBuildRunLogsDownCommands(program) {
     });
 
   program.command('down-app <app>')
-    .description('Stop and remove application container; optionally remove volume and image')
+    .description('Stop and remove app container (--volumes removes data volume)')
     .option('--volumes', 'Remove application Docker volume')
     .action(async(appName, options) => {
       try {
@@ -242,7 +264,7 @@ function setupBuildRunLogsDownCommands(program) {
 
 function setupShellTestStopCommands(program) {
   program.command('stop <app>')
-    .description('Stop and remove application container (alias for down-app)')
+    .description('Alias for down-app: stop and remove container')
     .option('--volumes', 'Remove application Docker volume')
     .action(async(appName, options) => {
       try {
@@ -255,7 +277,7 @@ function setupShellTestStopCommands(program) {
     });
 
   program.command('shell <app>')
-    .description('Open interactive shell in the application container')
+    .description('Interactive shell in running or ephemeral container')
     .option('--env <env>', 'Environment (dev|tst); dev uses running container', 'dev')
     .action(async(appName, options) => {
       try {
@@ -266,105 +288,20 @@ function setupShellTestStopCommands(program) {
         process.exit(1);
       }
     });
-
-  program.command('test <app>')
-    .description('Run tests (builder app: in container; external system: local validation)')
-    .option('--env <env>', 'For builder app: dev (running container) or tst (ephemeral)', 'dev')
-    .option('-d, --datasource <key>', 'For external system: test specific datasource only')
-    .option('-v, --verbose', 'Verbose output')
-    .action(async(appName, options) => {
-      try {
-        const pathsUtil = require('../utils/paths');
-        const appType = await pathsUtil.detectAppType(appName).catch(() => null);
-        if (appType && appType.baseDir === 'integration') {
-          const test = require('../external-system/test');
-          const results = await test.testExternalSystem(appName, options);
-          test.displayTestResults(results, options.verbose);
-          if (!results.valid) process.exit(1);
-        } else {
-          const { runAppTest } = require('../commands/app-test');
-          await runAppTest(appName, { env: options.env });
-        }
-      } catch (error) {
-        handleCommandError(error, 'test');
-        process.exit(1);
-      }
-    });
 }
 
-async function runTestE2ECommand(appName, options) {
-  const pathsUtil = require('../utils/paths');
-  const appType = await pathsUtil.detectAppType(appName).catch(() => null);
-  if (appType && appType.baseDir === 'integration') {
-    const { runTestE2EForExternalSystem } = require('../commands/test-e2e-external');
-    const { success, results } = await runTestE2EForExternalSystem(appName, {
-      env: options.env,
-      debug: options.debug,
-      verbose: options.verbose,
-      async: options.async !== false
-    });
-    results.forEach(r => {
-      const icon = r.success ? chalk.green('✓') : chalk.red('✗');
-      const msg = r.error ? `${r.key}: ${r.error}` : r.key;
-      logger.log(`  ${icon} ${msg}`);
-    });
-    if (!success) process.exit(1);
-    return;
-  }
-  const { runAppTestE2e } = require('../commands/app-test');
-  await runAppTestE2e(appName, { env: options.env });
-}
-
-function setupInstallTestE2eLintCommands(program) {
-  program.command('install <app>')
-    .description('Install dependencies in container (builder apps only)')
-    .option('--env <env>', 'dev (running container) or tst (ephemeral with .env)', 'dev')
-    .action(async(appName, options) => {
-      try {
-        const pathsUtil = require('../utils/paths');
-        const appType = await pathsUtil.detectAppType(appName).catch(() => null);
-        if (appType && appType.baseDir === 'integration') {
-          logger.log(chalk.gray('Install is for builder applications only. Use aifabrix shell <app> to run commands in external setups.'));
-          return;
-        }
-        const { runAppInstall } = require('../commands/app-install');
-        await runAppInstall(appName, { env: options.env });
-      } catch (error) {
-        handleCommandError(error, 'install');
-        process.exit(1);
-      }
-    });
-
-  program.command('test-e2e <app>')
-    .description('Run e2e tests (builder: in container; external system: all datasources via dataplane)')
-    .option('-e, --env <env>', 'Environment: dev, tst, or pro (builder: dev/tst for container)')
-    .option('-v, --verbose', 'Show detailed step output and poll progress')
-    .option('--debug', 'Include debug output and write log to integration/<app>/logs/')
-    .option('--no-async', 'Use sync mode (no polling); single POST per datasource')
-    .action(async(appName, options) => {
-      try {
-        await runTestE2ECommand(appName, options);
-      } catch (error) {
-        handleCommandError(error, 'test-e2e');
-        process.exit(1);
-      }
-    });
-
-  program.command('lint <app>')
-    .description('Run lint in container (builder apps only)')
-    .option('--env <env>', 'dev (running container) or tst (ephemeral with .env)', 'dev')
+function setupDockerfileGenerateCommand(program) {
+  program.command('dockerfile <app>')
+    .description('Generate Dockerfile from detected runtime')
+    .option('-l, --language <lang>', 'Override language detection')
+    .option('-f, --force', 'Overwrite existing Dockerfile')
     .action(async(appName, options) => {
       try {
-        const pathsUtil = require('../utils/paths');
-        const appType = await pathsUtil.detectAppType(appName).catch(() => null);
-        if (appType && appType.baseDir === 'integration') {
-          logger.log(chalk.gray('lint is for builder applications only. Use aifabrix shell <app> then make lint or pnpm lint.'));
-          return;
-        }
-        const { runAppLint } = require('../commands/app-test');
-        await runAppLint(appName, { env: options.env });
+        const dockerfilePath = await app.generateDockerfileForApp(appName, options);
+        logger.log(formatSuccessParagraph('Dockerfile generated successfully!'));
+        logger.log(chalk.gray(`Location: ${dockerfilePath}`));
       } catch (error) {
-        handleCommandError(error, 'lint');
+        handleCommandError(error, 'dockerfile');
         process.exit(1);
       }
     });
@@ -373,6 +310,7 @@ function setupInstallTestE2eLintCommands(program) {
 function setupPushDeployDockerfileCommands(program) {
   program.command('push <app>')
     .description('Push image to Azure Container Registry')
+    .addHelpText('after', PUSH_HELP_AFTER)
     .option('-r, --registry <registry>', 'ACR registry URL (overrides application.yaml)')
     .option('-t, --tag <tag>', 'Image tag(s) - comma-separated for multiple (default: latest)')
     .action(async(appName, options) => {
@@ -385,15 +323,26 @@ function setupPushDeployDockerfileCommands(program) {
     });
 
   program.command('deploy <app>')
-    .description('Deploy to Azure or locally via Miso Controller')
+    .description('Deploy via Miso Controller (Azure or --local)')
+    .addHelpText('after', DEPLOY_HELP_AFTER)
     .option('--local', 'Send manifest to controller then run app locally (app: same as aifabrix run <app>; external: restart dataplane)')
     .option('--client-id <id>', 'Client ID (overrides config)')
     .option('--client-secret <secret>', 'Client Secret (overrides config)')
     .option('--poll', 'Poll for deployment status', true)
     .option('--no-poll', 'Do not poll for status')
+    .option('--probe', 'After external deploy, run dataplane runtime checks (validation/run); slower')
+    .option('--probe-timeout <ms>', 'Timeout for --probe on external deploy (default: 120000)', '120000')
     .action(async(appName, options) => {
       try {
-        const opts = { ...options, local: !!options.local };
+        const probeTimeout =
+          options.probeTimeout === undefined || options.probeTimeout === null
+            ? 120000
+            : Number(options.probeTimeout);
+        const opts = {
+          ...options,
+          local: !!options.local,
+          probeTimeout: Number.isFinite(probeTimeout) ? probeTimeout : 120000
+        };
         const outcome = await app.deployApp(appName, opts);
         if (opts.local && outcome) {
           if (outcome.usedExternalDeploy) await app.restartApp('dataplane');
@@ -405,20 +354,7 @@ function setupPushDeployDockerfileCommands(program) {
       }
     });
 
-  program.command('dockerfile <app>')
-    .description('Generate Dockerfile for an application')
-    .option('-l, --language <lang>', 'Override language detection')
-    .option('-f, --force', 'Overwrite existing Dockerfile')
-    .action(async(appName, options) => {
-      try {
-        const dockerfilePath = await app.generateDockerfileForApp(appName, options);
-        logger.log(chalk.green('\n✅ Dockerfile generated successfully!'));
-        logger.log(chalk.gray(`Location: ${dockerfilePath}`));
-      } catch (error) {
-        handleCommandError(error, 'dockerfile');
-        process.exit(1);
-      }
-    });
+  setupDockerfileGenerateCommand(program);
 }
 
 /**

package/lib/cli/setup-app.test-commands.js

@@ -0,0 +1,179 @@
+/**
+ * @fileoverview CLI test/install/lint command setup (builder app + external integration dispatch).
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const { handleCommandError } = require('../utils/cli-utils');
+const { TEST_HELP_AFTER, TEST_E2E_HELP_AFTER } = require('./setup-app.help');
+
+function setupTestCommand(program) {
+  program.command('test <app>')
+    .description('Tests: builder in container; external = local validation')
+    .option('-e, --env <env>', 'For builder app: dev (running container) or tst (ephemeral)', 'dev')
+    .option('-v, --verbose', 'Verbose output')
+    .option('-d, --debug', 'Write debug log to integration/<systemKey>/logs/ (external only)')
+    .option(
+      '--sync',
+      'Not supported for this command (local validation only). Use aifabrix upload <systemKey> or dataplane test commands with --sync.'
+    )
+    .addHelpText('after', TEST_HELP_AFTER)
+    .action(async(appName, options, cmd) => {
+      try {
+        const rawArgs = Array.isArray(cmd?.rawArgs) ? cmd.rawArgs : [];
+        const envExplicit = rawArgs.includes('-e') || rawArgs.includes('--env');
+        const pathsUtil = require('../utils/paths');
+        const appType = await pathsUtil.detectAppType(appName).catch(() => null);
+        if (options.sync === true) {
+          throw new Error(
+            'Option --sync is not supported for aifabrix test (local or container runs do not publish to the dataplane). ' +
+              'Use: aifabrix upload <systemKey>, then aifabrix test-integration <systemKey> --sync or aifabrix datasource test-integration <datasourceKey> --sync.'
+          );
+        }
+        if (appType && appType.baseDir === 'integration') {
+          const test = require('../external-system/test');
+          const externalOpts = {
+            ...options,
+            // Keep help default but don't override auth/env behavior unless user explicitly set it.
+            env: envExplicit ? options.env : undefined
+          };
+          const results = await test.testExternalSystem(appName, externalOpts);
+          test.displayTestResults(results, options.verbose, appName);
+          if (!results.valid) process.exit(1);
+          return;
+        }
+        const { runAppTest } = require('../commands/app-test');
+        await runAppTest(appName, { env: options.env });
+      } catch (error) {
+        handleCommandError(error, 'test');
+        process.exit(1);
+      }
+    });
+}
+
+async function runTestE2ECommand(appName, options) {
+  const pathsUtil = require('../utils/paths');
+  const appType = await pathsUtil.detectAppType(appName).catch(() => null);
+  if (options.sync === true && appType && appType.baseDir === 'builder') {
+    throw new Error(
+      'Option --sync applies only to external integration E2E (integration/<systemKey>/). ' +
+        'Remove --sync for builder app E2E, or use aifabrix upload from the integration folder first.'
+    );
+  }
+  if (appType && appType.baseDir === 'integration') {
+    const { runTestE2EForExternalSystem } = require('../commands/test-e2e-external');
+    const { success, results } = await runTestE2EForExternalSystem(appName, {
+      env: options.env,
+      debug: options.debug,
+      verbose: options.verbose,
+      async: options.async !== false,
+      sync: options.sync === true
+    });
+    const { displayIntegrationTestResults } = require('../utils/external-system-display');
+    displayIntegrationTestResults(
+      {
+        systemKey: appName,
+        success,
+        datasourceResults: results.map(r => ({
+          key: r.key,
+          success: r.success,
+          error: r.error,
+          skipped: false,
+          datasourceTestRun: r.datasourceTestRun
+        }))
+      },
+      options.verbose,
+      { debug: options.debug, runType: 'e2e' }
+    );
+    if (!success) process.exit(1);
+    return;
+  }
+  const { runAppTestE2e } = require('../commands/app-test');
+  await runAppTestE2e(appName, { env: options.env });
+}
+
+function setupInstallCommand(program) {
+  program.command('install <app>')
+    .description('Install deps in container (builder apps only)')
+    .option('--env <env>', 'dev (running container) or tst (ephemeral with .env)', 'dev')
+    .action(async(appName, options) => {
+      try {
+        const pathsUtil = require('../utils/paths');
+        const appType = await pathsUtil.detectAppType(appName).catch(() => null);
+        if (appType && appType.baseDir === 'integration') {
+          logger.log(
+            chalk.gray('Install is for builder applications only. Use aifabrix shell <app> to run commands in external setups.')
+          );
+          return;
+        }
+        const { runAppInstall } = require('../commands/app-install');
+        await runAppInstall(appName, { env: options.env });
+      } catch (error) {
+        handleCommandError(error, 'install');
+        process.exit(1);
+      }
+    });
+}
+
+function setupTestE2eCommand(program) {
+  program.command('test-e2e <app>')
+    .description('E2E: builder in container; external = all datasources via dataplane')
+    .option('-e, --env <env>', 'Environment: dev, tst, or pro (builder: dev/tst for container)', 'dev')
+    .option('-v, --verbose', 'Show detailed step output and poll progress')
+    .option('-d, --debug', 'Include debug output and write log to integration/<systemKey>/logs/')
+    .option(
+      '--sync',
+      'Publish local system and datasource files to the dataplane before running E2E (same as aifabrix upload <systemKey>; external integration only)'
+    )
+    .addHelpText('after', TEST_E2E_HELP_AFTER)
+    .action(async(appName, options, cmd) => {
+      try {
+        const rawArgs = Array.isArray(cmd?.rawArgs) ? cmd.rawArgs : [];
+        const envExplicit = rawArgs.includes('-e') || rawArgs.includes('--env');
+        const externalOpts = {
+          ...options,
+          env: envExplicit ? options.env : undefined,
+          async: true // system-level command surface omits --no-async; always poll for completeness
+        };
+        await runTestE2ECommand(appName, externalOpts);
+      } catch (error) {
+        handleCommandError(error, 'test-e2e');
+        process.exit(1);
+      }
+    });
+}
+
+function setupLintCommand(program) {
+  program.command('lint <app>')
+    .description('Lint in container (builder apps only)')
+    .option('--env <env>', 'dev (running container) or tst (ephemeral with .env)', 'dev')
+    .action(async(appName, options) => {
+      try {
+        const pathsUtil = require('../utils/paths');
+        const appType = await pathsUtil.detectAppType(appName).catch(() => null);
+        if (appType && appType.baseDir === 'integration') {
+          logger.log(chalk.gray('lint is for builder applications only. Use aifabrix shell <app> then make lint or pnpm lint.'));
+          return;
+        }
+        const { runAppLint } = require('../commands/app-test');
+        await runAppLint(appName, { env: options.env });
+      } catch (error) {
+        handleCommandError(error, 'lint');
+        process.exit(1);
+      }
+    });
+}
+
+function setupInstallTestE2eLintCommands(program) {
+  setupInstallCommand(program);
+  setupTestCommand(program);
+  setupTestE2eCommand(program);
+  setupLintCommand(program);
+}
+
+module.exports = {
+  setupInstallTestE2eLintCommands
+};
+

package/lib/cli/setup-auth.js

@@ -14,9 +14,22 @@ const { handleLogout } = require('../commands/logout');
 const { handleAuthStatus } = require('../commands/auth-status');
 const { handleAuthConfig } = require('../commands/auth-config');
 
+const LOGIN_HELP_AFTER = `
+Examples:
+  $ aifabrix login
+  $ aifabrix login -m credentials -a myapp -e dev
+`;
+
+const AUTH_HELP_AFTER = `
+Without options: show auth status (same as: aifabrix auth status).
+With --set-controller or --set-environment: write defaults to config.yaml.
+Subcommand: auth status [--validate] for CI/scripts.
+`;
+
 function setupLoginCommand(program) {
   program.command('login')
-    .description('Authenticate with Miso Controller')
+    .description('Sign in to Miso Controller (device or credentials flow)')
+    .addHelpText('after', LOGIN_HELP_AFTER)
     .option('-c, --controller <url>', 'Controller URL (default: from config or developer ID, e.g. http://localhost:3000)')
     .option('-m, --method <method>', 'Authentication method (device|credentials)', 'device')
     .option('-a, --app <app>', 'Application name (required for credentials method, reads from secrets.local.yaml)')
@@ -29,7 +42,7 @@ function setupLoginCommand(program) {
       try {
         await handleLogin(options);
       } catch (error) {
-        logger.error(chalk.red('\n❌ Login failed:'), error.message);
+        logger.error(chalk.red('\n✖ Login failed:'), error.message);
         process.exit(1);
       }
     });
@@ -37,7 +50,7 @@ function setupLoginCommand(program) {
 
 function setupLogoutCommand(program) {
   program.command('logout')
-    .description('Clear authentication tokens')
+    .description('Clear stored tokens (optional filter by controller/env/app)')
     .option('-c, --controller <url>', 'Clear device tokens for specific controller')
     .option('-e, --environment <env>', 'Clear client tokens for specific environment')
     .option('-a, --app <app>', 'Clear client tokens for specific app (requires --environment)')
@@ -61,7 +74,8 @@ function setupAuthSubcommands(program) {
     }
   };
   const auth = program.command('auth')
-    .description('Authentication status and config (controller, environment)')
+    .description('Show auth status or set default controller/environment')
+    .addHelpText('after', AUTH_HELP_AFTER)
     .option('--set-controller <url>', 'Set default controller URL in config')
     .option('--set-environment <env>', 'Set default environment in config')
     .action(async(options) => {
@@ -82,7 +96,7 @@ function setupAuthSubcommands(program) {
       }
     });
   auth.command('status')
-    .description('Display authentication status for current controller and environment')
+    .description('Show tokens/session for current controller and environment')
     .option('--validate', 'Exit with code 1 when not authenticated (for scripted use, e.g. manual test setup)')
     .action(authStatusHandler);
 }

package/lib/cli/setup-credential-deployment.js

@@ -15,10 +15,22 @@ const { runCredentialEnv } = require('../commands/credential-env');
 const { runCredentialPush } = require('../commands/credential-push');
 const { runDeploymentList } = require('../commands/deployment-list');
 
+const CREDENTIAL_HELP_AFTER = `
+Subcommands:
+  env <systemKey>   Prompt for KV_* values → integration/<key>/.env
+  push <systemKey>  Upload secrets from .env to Dataplane
+  list               List credentials (pagination: --page-size)
+`;
+
+const DEPLOYMENT_HELP_AFTER = `
+Subcommand:
+  list   Recent deployments for the current environment
+`;
+
 function setupCredentialEnvAndPush(credential) {
   credential
-    .command('env <system-key>')
-    .description('Prompt for KV_* credential values and write integration/<system-key>/.env')
+    .command('env <systemKey>')
+    .description('Interactive KV_* prompts → integration/<key>/.env')
     .action(async(systemKey, _options) => {
       try {
         await runCredentialEnv(systemKey);
@@ -29,8 +41,8 @@ function setupCredentialEnvAndPush(credential) {
       }
     });
   credential
-    .command('push <system-key>')
-    .description('Push credential secrets from .env to Dataplane (KV_* vars)')
+    .command('push <systemKey>')
+    .description('Push KV_* secrets from .env to Dataplane')
     .action(async(systemKey, _options) => {
       try {
         await runCredentialPush(systemKey);
@@ -49,11 +61,12 @@ function setupCredentialEnvAndPush(credential) {
 function setupCredentialDeploymentCommands(program) {
   const credential = program
     .command('credential')
-    .description('Manage credentials');
+    .description('Dataplane credentials: env, push, list')
+    .addHelpText('after', CREDENTIAL_HELP_AFTER);
   setupCredentialEnvAndPush(credential);
   credential
     .command('list')
-    .description('Get credentials from Dataplane')
+    .description('List credentials from Dataplane')
     .option('--active-only', 'List only active credentials')
     .option('--page-size <n>', 'Items per page', '50')
     .action(async(options) => {
@@ -72,11 +85,12 @@ function setupCredentialDeploymentCommands(program) {
 
   const deployment = program
     .command('deployment')
-    .description('List deployments');
+    .description('Controller deployments (list)')
+    .addHelpText('after', DEPLOYMENT_HELP_AFTER);
 
   deployment
     .command('list')
-    .description('List last N deployments for current environment (default pageSize=50)')
+    .description('List recent deployments for current environment')
     .option('--controller <url>', 'Controller URL (default: from config)')
     .option('--environment <env>', 'Environment key (default: from config)')
     .option('--page-size <n>', 'Items per page', '50')