# No hidden or undocumented commands

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

## Why it matters

Hidden commands are where CLI trust goes to die. When README documents a feature that does not appear in `--help`, or when `mytool` shows four commands but actually ships seven, users stop believing the help output is authoritative. They start grepping source or running `strings` on the binary. Commands registered without descriptions also silently vanish from generated docs and shell completions, leaving users to discover functionality through support tickets and tribal knowledge.

## Severity rationale

Low because hidden commands cause discoverability friction but rarely break working integrations.

## Remediation

Audit every `.hideHelp()`, `Hidden: true`, or `hidden=True` flag in `src/cli/commands/` and remove it from user-facing commands. Any command useful to end users must appear in `--help` output with a description:

```ts
program
  .command('export')
  .description('Export data to CSV or JSON format')
  .action(exportData)
```

Reserve the hidden flag for internal debug-only tooling.

## Detection

- **ID:** `no-hidden-commands`
- **Severity:** `low`
- **What to look for:** List all commands registered in the CLI codebase. For each, compare the list of registered commands in source code against what appears in `--help` output. Check for commands explicitly marked as hidden (commander `.hideHelp()`, cobra `Hidden: true`, click `hidden=True`). Check for commands registered but with no description (which may not appear in help listings depending on the framework).
- **Pass criteria:** All commands that a user could run are discoverable via `--help`. Hidden commands are acceptable only if they are genuinely internal/debug (not user-facing functionality). No functionality is only accessible by knowing an undocumented command name — 0% of functional commands should be undocumented in --help output. Report: "X commands found, all Y documented in help output."
- **Fail criteria:** User-facing functionality is hidden from help output, or commands are registered without descriptions and silently omitted from help listings.
- **Skip (N/A) when:** The CLI has a single command with no subcommands. All checks skip when no CLI entry point is detected.
- **Do NOT pass when:** Commands are registered in code but deliberately excluded from help output without a documented reason.
- **Detail on fail:** `"'export' command is marked hidden but is documented in the README as a user feature"` or `"2 commands ('sync', 'migrate') have no description and don't appear in --help output"`
- **Remediation:** If a command is useful to end users, it should be discoverable. Remove the hidden flag or add a description:

  ```ts
  // Remove hidden flag for user-facing commands
  program
    .command('export')
    .description('Export data to CSV or JSON format')  // now appears in --help
    .action(exportData)
  ```

  Reserve hidden commands for internal debugging tools only. If you have many commands and want to reduce help clutter, use command groups instead of hiding commands.

Taxons: user-experience

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