ax-check rule

AXC-F008: Claimed CLI command does not exist

The file shows a subcommand that the CLI's --help does not list.

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 drift
Applies toInstruction files and manifests
Pattern tagsdrift, agents-md, skills
Fix in one lineUpdate the instructions to the current command, or add an alias for the old one.

The file shows a subcommand of a CLI, and that CLI’s own --help does not list it. The instructions use a command that was renamed or removed. An agent that follows them gets an error, and has to work out the new command on its own.

What it checks

You tell ax-check which program to check with --cli "<command>", for example --cli invoicekit. ax-check reads the files for code spans and fenced code blocks that start with that program, and takes the word after it as the claimed subcommand. It then runs <command> --help, reads the list of commands (and their aliases) from the output, and compares. The rule fires when the subcommand is not listed. If a listed command is within a small edit distance of the claim, the message adds “Did you mean …”.

Passing --cli is your explicit request to run that program, so it works without --online. Point it only at a program that is safe to run with --help.

Why it matters

Instruction files such as AGENTS.md and SKILL.md are a large part of the documentation coding agents work with. In one study of 557 agentic coding sessions, instruction files and working notes made up 60.5% of the documentation interactions, against 1.3% for API references (paper’s claim; arXiv preprint, not peer reviewed). The same study reports that the link between consulting documentation and editing code is unresolved. A second preprint found that the gain from adding a rule to a skill came mainly from rules that name a command or path the old skill did not mention (paper’s claim, four agents, arXiv preprint). Neither study tested stale commands. That a stale command in these files gets followed is this rule’s design rationale, drawn from the second study’s finding that named commands change what agents do.

How to fix

  • Update the instructions to the current command.
  • Or add an alias in the CLI for the old command, if other people rely on it.
  • Check the full set of commands in the CLI’s --help and run the check again.

Example

Find it:

ax-check drift --cli invoicekit AGENTS.md

Before

# AGENTS.md

## Release

Run `invoicekit report --month 2026-09` to prepare the numbers.

The CLI’s --help lists summary and export, but no report. ax-check suggests export as the closest match.

After

# AGENTS.md

## Release

Run `invoicekit export --month 2026-09` to prepare the numbers.

How ax-check detects it

The extraction and the rule logic are deterministic, but the result depends on what the CLI’s help prints on the machine and version you run it against, so the same file can give different findings on another day. JSON and SARIF reports record when and where the check ran. It only runs for the program you name with --cli. It reads a code span or a fenced code line, splits it on &&, ||, ; and |, removes a leading $ , and tokenises it. The program must be at the start of the command (or after npx or bunx). The word that follows must look like a command (a lower-case word, which may contain -, _ or :). It then runs <command> --help and checks whether the word is among the commands parsed from that help text. Only the word directly after the program is read as a subcommand.

Known limits:

  • A CLI that prints help on a different path, or needs a login to print help, may produce no usable output.
  • A first argument that is a file or value rather than a subcommand (for example invoicekit input.csv) can look like a subcommand. Silence the rule for that file.
  • Commands that appear only in prose are not read.

Without --cli, this rule does not run. Add --dry-run to list the claims and see what would be compared, without running the program. To silence it, use --disable AXC-F008.

Sources

  • Paper: “From Agent Behaviour to Agent-Friendly Documentation”, Gao and Chen, arXiv 2608.20195, 20 Aug 2026. https://arxiv.org/abs/2608.20195 . Paper’s claim: in 557 agentic coding sessions, agent-facing artefacts were 60.5% of documentation interactions versus 1.3% for API references. Preprint, not peer reviewed.
  • Paper: “Agent Skill Evolution: How Revisions Affect Coding Agents”, Wang et al., arXiv 2610.04832, 4 Oct 2026. https://arxiv.org/abs/2610.04832 . Paper’s claim: across four agents an added rule raised the rate of the required action by +0.23 on average, mainly from rules that name a command or path the old skill did not mention. Preprint, not peer reviewed.

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.