ax-check rule

AXC-C009: Help is not reachable

None of --help, -h or help printed usage text with exit status 0.

ax-check is a checker being prepared for release. This page documents the rule ahead of that release; see all 50 rules.

Severityerror
KindObserved. Depends on the program and environment at run time.
Modeax-check probe-cli
Applies toCommand-line programs, run as a subprocess
Pattern tagsdiscovery, docs-for-agents
Fix in one lineMake --help print usage to stdout and exit 0, without needing credentials or a network.

None of --help, -h or help printed text and exited with status 0. For a command-line tool, help is how an agent finds out what the tool can do. Without it, the agent has only its memory, which may be out of date.

What it checks

The help probe tries <cmd> --help first, then <cmd> -h, then (only with --probe help-word) <cmd> help. The later variants run only if the earlier ones failed. The rule fires when none of them exits 0 with output, and a variant that timed out does not count. Output on stderr is accepted when stdout is empty.

Why it matters

Agents learn a CLI by reading its help. The Command Line Interface Guidelines say “-h, –help: Help. This should only mean help.” The GNU Coding Standards say every program should support --version and --help. Help also feeds the other checks: AXC-C006 and AXC-C008 read it, so when help is missing those checks have nothing to inspect. Research on agent behaviour suggests that agents lean heavily on agent-facing documents; Gao and Chen (arXiv 2608.20195, a preprint) report that in 557 agentic coding sessions, agent-facing artefacts such as instruction files were 60.5% of documentation interactions, against 1.3% for API references (the paper’s claim). That study is about coding sessions, not CLI help, and it did not measure help text. Reading it as a reason to keep help one flag away is this rule’s design rationale.

Common ways to fail are: help that needs a login or a network, help that exits non-zero, help that prints to stderr only, and help that treats --help as an unknown flag.

How to fix

Make --help print usage to stdout and exit 0, without credentials, a network call or a prompt. Keep -h working too if short flags are common in your ecosystem.

Example

Before

$ invoicer --help </dev/null; echo $?
error: not logged in. Run: invoicer login
1
$ invoicer -h </dev/null; echo $?
error: unknown flag -h
2

After

$ invoicer --help </dev/null; echo $?
Usage: invoicer <command> [options]

Commands:
  create   Create a draft invoice
  list     List invoices
  show     Show one invoice
  export   Export invoices

Run "invoicer <command> --help" for details.
0

A Node fix: handle the flag before any authentication step.

if (process.argv.includes('--help') || process.argv.includes('-h')) {
  process.stdout.write(usageText);
  process.exit(0);
}
await requireLogin();

How ax-check detects it

Each help variant runs with no TTY and stdin closed. A variant counts as reachable if it exits 0 and prints something. The rule only fires when every variant that ran failed. If a variant fails because the program could not start at all (exit 126 or 127, or a missing interpreter, file or dependency), ax-check stops with a usage error (exit 2) instead of reporting this rule. It does not judge the quality of the text.

To reproduce by hand: invoicer --help </dev/null; echo $?, then invoicer -h </dev/null; echo $?, then invoicer help </dev/null; echo $?.

Known false positives: a CLI that prints its help only after a successful network call. That is itself the thing the rule is warning about. Silence the rule with --disable AXC-C009 only if the program is not meant to be called by agents.

Safety note: This rule uses the default --help and -h probes. The help subcommand fallback is opt-in (--probe help-word), because a program without subcommands may read help as a file or target name. probe-cli executes your program under your own OS account. The temporary working directory and HOME it uses are not a sandbox: the program can still read and write anything your account can, and use the network. Probe a CLI you have not reviewed only inside a container or a throwaway virtual machine. Run ax-check probe-cli --dry-run -- invoicer first to see the probes that would run, and see the “Probe safety” section of the ax-check README for what is and is not isolated.

Sources

Records in the AX evidence register that share a pattern tag with this rule. A shared tag means the record is about the same pattern, not that it tests this rule. Read the evidence class before the number.