# Help flag produces usage information for every command

- **Pattern:** `ab-000639` (`cli-quality.command-structure.help-flag`)
- **Severity:** critical
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-000639
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-000639)

## Why it matters

A CLI without help text is a CLI no one can use. Users land on your tool via `npx mytool` or `pip install`, type `--help` out of reflex, and either see nothing or see a framework-default skeleton. They close the terminal and find a competitor. Missing descriptions also break shell autocomplete hints, man-page generation, and docs scrapers that harvest `--help` output. This is a user-experience failure severe enough to zero out adoption regardless of how good the underlying logic is.

## Severity rationale

Critical because without `--help` output the CLI is effectively undiscoverable and unusable for any new user.

## Remediation

Add a description to every `.command()`, `cobra.Command`, `@cli.command()`, or `#[command]` definition, and verify `--help` and `-h` produce usage text on the root command plus every subcommand. Ship descriptions in the same file the command is registered in — for example `src/cli/commands/deploy.ts`:

```ts
program
  .command('deploy')
  .description('Deploy the current project to production')
  .action(deploy)
```

## Detection

- **ID:** `help-flag`
- **Severity:** `critical`
- **What to look for:** Count all commands and subcommands in the CLI. For each, check that `--help` and `-h` produce usage information for the root command and every subcommand. In commander, verify `.description()` is set on every `.command()` call. In yargs, check that `.describe()` or `.usage()` is configured. In click/typer, verify docstrings exist on command functions. In cobra, check `Short` and `Long` fields on every `cobra.Command`. In clap, verify `about` or `long_about` on every `Command` or `#[command(about = "...")]` attribute.
- **Pass criteria:** Every registered command and subcommand has a description that will appear in `--help` output. The root command's `--help` lists all available subcommands. No command produces an empty or framework-default-only help screen — 100% of commands and subcommands must display help text when invoked with --help. Report the count: "X commands found, all Y respond to --help."
- **Fail criteria:** Any command is missing a description (will show blank in help output), or the root command does not list subcommands, or `--help`/`-h` is not wired up (manually overridden or disabled).
- **Skip (N/A) when:** All checks skip when no CLI entry point is detected. This specific check never skips otherwise — every CLI must have help text.
- **Cross-reference:** The `subcommand-pattern` check verifies the command hierarchy that --help should document.
- **Detail on fail:** `"3 of 7 subcommands have no .description() set — 'deploy', 'rollback', 'config' will show blank help text"` or `"Root command help does not list available subcommands — only shows global flags"`
- **Remediation:** Help text is how users discover your CLI's capabilities. Every command needs a description:

  ```ts
  // commander (Node.js)
  program
    .command('deploy')
    .description('Deploy the current project to production')
    .option('-e, --env <environment>', 'Target environment', 'production')
    .action(deploy)
  ```

  ```python
  # click (Python)
  @cli.command()
  @click.argument('target')
  def deploy(target):
      """Deploy the current project to the specified target."""
      pass
  ```

  ```go
  // cobra (Go)
  var deployCmd = &cobra.Command{
      Use:   "deploy [target]",
      Short: "Deploy the current project",
      Long:  "Deploy the current project to the specified target environment.",
      RunE:  runDeploy,
  }
  ```

Taxons: user-experience

HTML version: https://auditbuffet.com/patterns/ab-000639