feat(cli): LTRAC-612 show global options in subcommand help

[chanceaclark]

Jira: LTRAC-612

What/Why?

The root-level --env-path option (and -V, --version) are defined on the root program in packages/catalyst/src/cli/program.ts, but Commander does not include parent/global options in subcommand --help output by default. Running catalyst deploy --help, catalyst auth login --help, etc. omitted --env-path entirely, which made the option feel hidden to users reading per-command help.

This change applies .configureHelp({ showGlobalOptions: true }) directly at each Command definition site (root, every top-level command, and every nested subcommand like auth login, logs tail, project create). Commander's per-command config does not propagate to subcommands automatically, so the setting has to be repeated — an explicit per-command call was chosen over a recursive helper for readability.

Output is unchanged on catalyst --help; every subcommand now includes a new Global Options: section listing --env-path and -V, --version.

Testing

No runtime behavior changes — purely help-text formatting.

• pnpm typecheck, pnpm lint, and pnpm test (131 tests) pass in packages/catalyst.
• Manual verification via node dist/cli.js <cmd> --help:
  • catalyst --help — unchanged, still lists --env-path under Options.
  • catalyst deploy --help, build --help, start --help, version --help, telemetry --help, logs --help, logs tail --help, auth --help, auth login --help, project --help, project create --help — all now render a Global Options: section containing --env-path <path> and -V, --version.

Migration

None. No public API or behavior change.

[changeset-bot]

🦋 Changeset detected

Latest commit: bd9229e

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@bigcommerce/catalyst	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
catalyst	Ready	Preview, Comment	Apr 27, 2026 10:24pm

[github-actions]

Bundle Size Report

Comparing against baseline from ed76224 (2026-04-27).

No bundle size changes detected.

[chanceaclark]

Command-specific

node ./dist/cli.js auth --help                                                                                              ✔ 
◢ @bigcommerce/catalyst v1.0.0-alpha.3                                                                                                                                                       3:12:14 PM

Usage: @bigcommerce/catalyst auth [options] [command]

Manage authentication for the BigCommerce CLI.

Options:
  -h, --help         display help for command

Global Options:
  -V, --version      output the version number
  --env-path <path>  Path to environment file to load (relative to current working directory)

Commands:
  whoami [options]   Verify stored credentials and display store/project info.
  login [options]    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.
  logout             Remove stored credentials for the current project.
  help [command]     display help for command

Global

node ./dist/cli.js --help                                                                                                   ✔ 
◢ @bigcommerce/catalyst v1.0.0-alpha.3                                                                                                                                                       3:12:06 PM

Usage: @bigcommerce/catalyst [options] [command]

CLI tool for Catalyst development.

Configuration priority: flags > env file (--env-path) > process.env > .bigcommerce/project.json.
Run `catalyst <command> --help` for details on a specific command.

Options:
  -V, --version              output the version number
  --env-path <path>          Path to environment file to load (relative to current working directory)
  -h, --help                 display help for command

Commands:
  version                    Display detailed version information.
  start                      Start a local preview of your Catalyst storefront using the OpenNext Cloudflare adapter.
  build [options]            Build your Catalyst project using the OpenNext/Cloudflare build pipeline. Also runs a Wrangler dry-run to generate deployment artifacts.
  deploy [options]           Deploy your application to Cloudflare.
  logs                       View logs from your deployed application.
  project                    Manage your BigCommerce infrastructure project.
  auth                       Manage authentication for the BigCommerce CLI.
  telemetry [options] [arg]  View or change CLI telemetry collection status. Enabling telemetry helps BigCommerce support diagnose and troubleshoot errors you encounter when using the CLI.
  help [command]             display help for command

[jairo-bc]

Wonder if we are going to have more shared configurations over cli command objects? In that case we should incapsulate that logic.

[chanceaclark]

Claude initial did that, but I kinda hated it. I think the CLI rarely changes enough that it's fine not creating an abstraction for it – there might be a future case where we don't want to use --env-path in command so best to keep it flexible.

[jorgemoya]

Thanks, I ran into this yesterday.