Bug: 'squad <command> --help' (and '-h') silently runs the command instead of showing help #1201

Problem

Running squad <command> --help or squad <command> -h (for almost every subcommand) does not print help. Instead, the --help/-h flag is silently dropped and the command executes for real — sometimes with destructive side effects (init creates files, triage/watch starts a long-running poll loop, etc.).

Top-level help works fine:

• squad --help ✅ prints help
• squad -h ✅ prints help
• squad help ✅ prints help

But subcommand-level help is broken across almost the entire CLI surface:

• squad init --help ❌ actually runs init (writes files into the cwd)
• squad triage --help ❌ actually starts the triage loop
• squad watch --help ❌ same — starts the watch loop (known: Add in-product help (--help) for squad watch command #757)
• squad status --help ❌ runs status
• squad roles --help ❌ lists roles
• squad doctor --help ❌ runs the doctor
• squad version --help ❌ prints version (because version is matched first)
• …and the same is true for upgrade, migrate, hire, copilot, plugin, export, import, scrub-emails, start, nap, memory, consult, extract, subsquads, link, build, aspire, schedule, personal, preset, cast, rc, copilot-bridge, init-remote, rc-tunnel, discover, delegate, upstream, economy, scrub-emails …

Today only two commands actually intercept --help / -h:

• squad loop --help ✅ (handled inline in packages/squad-cli/src/cli-entry.ts around line 625)
• squad state-mcp --help ✅ (handled inline around line 427)

Every other command falls through to its real implementation with --help simply present in args.

Reproduction

Tested with @bradygaster/squad-cli v0.9.6-insider.3 on Windows (PowerShell 7) and Node 24.14.0 — but the bug is purely in the JS routing layer in packages/squad-cli/src/cli-entry.ts and is platform-independent.

In an empty directory:

mkdir /tmp/squad-help-bug && cd /tmp/squad-help-bug
squad init --help
# Expected: help text for the init command
# Actual:   init runs for real and creates .squad/, .github/, .gitignore, .gitattributes, .copilot/

squad triage --help
# Expected: help text for the triage command
# Actual:   starts the triage polling loop (Ctrl+C needed)

squad doctor --help
# Expected: help text for the doctor command
# Actual:   runs the doctor health check

squad status --help
# Expected: help text for the status command
# Actual:   prints the current squad status report

Root cause

In packages/squad-cli/src/cli-entry.ts:

1. Lines 144–147 handle --version / -v / version.
2. Lines 150–283 handle the top-level --help / -h / help (only when it is the first arg).
3. The routes that follow each switch on cmd (init, status, doctor, etc.) but do not check for --help first before executing.

Result: --help lands in args as a no-op flag and the command runs.

Desired behavior

For every subcommand, squad <cmd> --help (and -h) should:

1. Print help text and exit 0.
2. Never trigger the command's real side effects.
3. Be intercepted in one place at the top of the router so we don't have to remember per command.

Per-command help text should at minimum describe: what the command does, usage, flags. For commands with rich inline help today (loop, state-mcp), behavior should be preserved.

Proposed fix (rough)

In main() in cli-entry.ts, after the top-level --help block and before the per-command routing, add:

if (cmd && cmd !== 'help' && cmd !== '--help' && cmd !== '-h'
    && cmd !== 'version' && cmd !== '--version' && cmd !== '-v'
    && (args.includes('--help') || args.includes('-h'))) {
  printCommandHelp(cmd);
  return;
}

…where printCommandHelp is a small switch that returns command-specific help (extracted from the existing top-level help blob), falling back to a friendly "no detailed help for X — see squad help" message for commands without a dedicated block. Existing inline handlers in loop and state-mcp can call into the same helper to remove duplication.

Related

• Add in-product help (--help) for squad watch command #757 — Add in-product help for squad watch (CLOSED, never fixed; this issue is broader and supersedes it).
• Bug: squad externalize and squad internalize missing from squad --help output #1050 — externalize / internalize missing from top-level help (different but adjacent UX bug).

Severity

User-facing UX bug with destructive potential: squad init --help writes files into the cwd; squad triage --help / watch --help starts a long-running daemon. The current behavior actively trains users out of using --help on this CLI.

Environment

• @bradygaster/squad-cli v0.9.6-insider.3
• Node.js v24.14.0
• Windows / PowerShell 7
• Behavior reproduces on dev branch HEAD (verified by reading packages/squad-cli/src/cli-entry.ts).

Willing to fix

Yes — I'd like to open a PR for this. Will follow the branch / changeset / draft-PR workflow from CONTRIBUTING.md.