feat(cli): add Commander.js built-in help text to all commands (#2984)

Add .description(), .addHelpText(), and .summary() to all CLI commands
so that `catalyst <command> --help` becomes the canonical reference.
Hide internal-only options (--api-host, --login-url) from help output.

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: chanceaclark

.changeset/cli-built-in-help-text.md

@@ -0,0 +1,5 @@
+---
+"@bigcommerce/catalyst": patch
+---
+
+Add built-in help text to all CLI commands so `catalyst <command> --help` is the canonical reference.

packages/catalyst/src/cli/commands/auth.ts

@@ -40,6 +40,14 @@ async function fetchStoreProfile(storeHash: string, accessToken: string, apiHost
 
 const whoami = new Command('whoami')
   .description('Verify stored credentials and display store/project info.')
+  .addHelpText(
+    'after',
+    `
+Example:
+  $ catalyst auth whoami
+
+  Logged in to My Store (abc123), connected to project my-project (43eba682-0c48-11f1-9bd5-827a48b0ce1e)`,
+  )
   .addOption(
     new Option(
       '--store-hash <hash>',
@@ -55,7 +63,8 @@ const whoami = new Command('whoami')
   .addOption(
     new Option('--api-host <host>', 'BigCommerce API host. The default is api.bigcommerce.com.')
       .env('BIGCOMMERCE_API_HOST')
-      .default('api.bigcommerce.com'),
+      .default('api.bigcommerce.com')
+      .hideHelp(),
   )
   .action(async (options) => {
     try {
@@ -110,7 +119,19 @@ const whoami = new Command('whoami')
   });
 
 const login = new Command('login')
-  .description('Authenticate via browser using the OAuth device code flow.')
+  .description(
+    'Authenticate via browser using the OAuth device code flow. If already logged in, displays current credentials and suggests running `catalyst auth logout` to re-authenticate.',
+  )
+  .addHelpText(
+    'after',
+    `
+Examples:
+  # Login via browser (recommended)
+  $ catalyst auth login
+
+  # Login with existing credentials (skips browser flow)
+  $ catalyst auth login --store-hash <STORE_HASH> --access-token <ACCESS_TOKEN>`,
+  )
   .addOption(
     new Option(
       '--store-hash <hash>',
@@ -126,7 +147,8 @@ const login = new Command('login')
   .addOption(
     new Option('--login-url <url>', 'BigCommerce login URL.')
       .env('BIGCOMMERCE_LOGIN_URL')
-      .default(DEFAULT_LOGIN_URL),
+      .default(DEFAULT_LOGIN_URL)
+      .hideHelp(),
   )
   .action(async (options) => {
     try {
@@ -183,6 +205,12 @@ const login = new Command('login')
 
 const logout = new Command('logout')
   .description('Remove stored credentials for the current project.')
+  .addHelpText(
+    'after',
+    `
+Example:
+  $ catalyst auth logout`,
+  )
   .action(() => {
     try {
       const config = getProjectConfig();

packages/catalyst/src/cli/commands/build.ts

@@ -76,6 +76,18 @@ export async function buildCatalystProject(projectUuid: string): Promise<void> {
 }
 
 export const build = new Command('build')
+  .description(
+    'Build your Catalyst project using the OpenNext/Cloudflare build pipeline. Also runs a Wrangler dry-run to generate deployment artifacts.',
+  )
+  .addHelpText(
+    'after',
+    `
+Examples:
+  $ catalyst build
+
+  # Include project UUID
+  $ catalyst build --project-uuid <UUID>`,
+  )
   .addOption(
     new Option(
       '--project-uuid <uuid>',

packages/catalyst/src/cli/commands/deploy.ts

@@ -370,6 +370,12 @@ export const fetchProject = async (
 
 export const deploy = new Command('deploy')
   .description('Deploy your application to Cloudflare.')
+  .addHelpText(
+    'after',
+    `
+Example:
+  $ catalyst deploy --secret BIGCOMMERCE_STORE_HASH=<YOUR_STORE_HASH> --secret BIGCOMMERCE_STOREFRONT_TOKEN=<YOUR_STOREFRONT_TOKEN>`,
+  )
   .addOption(
     new Option(
       '--store-hash <hash>',
@@ -385,7 +391,8 @@ export const deploy = new Command('deploy')
   .addOption(
     new Option('--api-host <host>', 'BigCommerce API host. The default is api.bigcommerce.com.')
       .env('BIGCOMMERCE_API_HOST')
-      .default('api.bigcommerce.com'),
+      .default('api.bigcommerce.com')
+      .hideHelp(),
   )
   .addOption(
     new Option(

packages/catalyst/src/cli/commands/logs.ts

@@ -233,6 +233,18 @@ export const tailLogs = async (
 
 const tail = new Command('tail')
   .description('Tail live logs from your deployed application.')
+  .addHelpText(
+    'after',
+    `
+Examples:
+  $ catalyst logs tail
+
+  # Tail logs with request format
+  $ catalyst logs tail --format request
+
+  # Tail logs as raw JSON (useful for piping to other tools)
+  $ catalyst logs tail --format json`,
+  )
   .addOption(storeHashOption().makeOptionMandatory())
   .addOption(accessTokenOption().makeOptionMandatory())
   .addOption(apiHostOption())
@@ -263,6 +275,12 @@ const tail = new Command('tail')
 
 const query = new Command('query')
   .description('Query historical logs from your deployed application.')
+  .addHelpText(
+    'after',
+    `
+Example:
+  $ catalyst logs query`,
+  )
   .addOption(storeHashOption().makeOptionMandatory())
   .addOption(accessTokenOption().makeOptionMandatory())
   .addOption(apiHostOption())

packages/catalyst/src/cli/commands/project.ts

@@ -8,6 +8,12 @@ import { getTelemetry } from '../lib/telemetry';
 
 const list = new Command('list')
   .description('List BigCommerce infrastructure projects for your store.')
+  .addHelpText(
+    'after',
+    `
+Example:
+  $ catalyst project list`,
+  )
   .addOption(
     new Option(
       '--store-hash <hash>',
@@ -23,7 +29,8 @@ const list = new Command('list')
   .addOption(
     new Option('--api-host <host>', 'BigCommerce API host. The default is api.bigcommerce.com.')
       .env('BIGCOMMERCE_API_HOST')
-      .default('api.bigcommerce.com'),
+      .default('api.bigcommerce.com')
+      .hideHelp(),
   )
   .action(async (options) => {
     const config = getProjectConfig();
@@ -55,6 +62,12 @@ const create = new Command('create')
   .description(
     'Create a new BigCommerce infrastructure project and link it to your local Catalyst project.',
   )
+  .addHelpText(
+    'after',
+    `
+Example:
+  $ catalyst project create`,
+  )
   .addOption(
     new Option(
       '--store-hash <hash>',
@@ -70,7 +83,8 @@ const create = new Command('create')
   .addOption(
     new Option('--api-host <host>', 'BigCommerce API host. The default is api.bigcommerce.com.')
       .env('BIGCOMMERCE_API_HOST')
-      .default('api.bigcommerce.com'),
+      .default('api.bigcommerce.com')
+      .hideHelp(),
   )
   .action(async (options) => {
     const config = getProjectConfig();
@@ -99,6 +113,16 @@ export const link = new Command('link')
   .description(
     'Link your local Catalyst project to a BigCommerce infrastructure project. You can provide a project UUID directly, or fetch and select from available projects using your store credentials.',
   )
+  .addHelpText(
+    'after',
+    `
+Examples:
+  # Link interactively (prompts to select or create)
+  $ catalyst project link
+
+  # Link using a project UUID directly
+  $ catalyst project link --project-uuid <UUID>`,
+  )
   .addOption(
     new Option(
       '--store-hash <hash>',
@@ -114,7 +138,8 @@ export const link = new Command('link')
   .addOption(
     new Option('--api-host <host>', 'BigCommerce API host. The default is api.bigcommerce.com.')
       .env('BIGCOMMERCE_API_HOST')
-      .default('api.bigcommerce.com'),
+      .default('api.bigcommerce.com')
+      .hideHelp(),
   )
   .option(
     '--project-uuid <uuid>',

packages/catalyst/src/cli/commands/start.ts

@@ -9,6 +9,12 @@ export const start = new Command('start')
   .description(
     'Start a local preview of your Catalyst storefront using the OpenNext Cloudflare adapter.',
   )
+  .addHelpText(
+    'after',
+    `
+Example:
+  $ catalyst start`,
+  )
   .action(async () => {
     const envLocal = join(process.cwd(), '.env.local');
     const devVars = join(process.cwd(), '.bigcommerce', '.dev.vars');

packages/catalyst/src/cli/commands/telemetry.ts

@@ -8,6 +8,22 @@ const telemetryService = getTelemetry();
 let isEnabled = telemetryService.isEnabled();
 
 export const telemetry = new Command('telemetry')
+  .description(
+    'View or change CLI telemetry collection status. Enabling telemetry helps BigCommerce support diagnose and troubleshoot errors you encounter when using the CLI.',
+  )
+  .addHelpText(
+    'after',
+    `
+Examples:
+  # Show telemetry status
+  $ catalyst telemetry
+
+  # Enable telemetry collection
+  $ catalyst telemetry enable
+
+  # Disable telemetry collection
+  $ catalyst telemetry --disable`,
+  )
   .addArgument(new Argument('[arg]').choices(['disable', 'enable', 'status']))
   .addOption(new Option('--enable', `Enables CLI telemetry collection.`).conflicts('disable'))
   .option('--disable', `Disables CLI telemetry collection.`)

packages/catalyst/src/cli/commands/version.ts

@@ -5,6 +5,12 @@ import { consola } from '../lib/logger';
 
 export const version = new Command('version')
   .description('Display detailed version information.')
+  .addHelpText(
+    'after',
+    `
+Example:
+  $ catalyst version`,
+  )
   .action(() => {
     consola.log('Version Information:');
     consola.log(`CLI Version: ${PACKAGE_INFO.version}`);

packages/catalyst/src/cli/index.spec.ts

@@ -17,7 +17,7 @@ describe('CLI program', () => {
     expect(program).toBeInstanceOf(Command);
     expect(program.name()).toBe(process.env.npm_package_name);
     expect(program.version()).toBe(process.env.npm_package_version);
-    expect(program.description()).toBe('CLI tool for Catalyst development');
+    expect(program.description()).toContain('CLI tool for Catalyst development');
   });
 
   test('has expected commands', () => {