ax-check rule

AXC-C005: Unknown command gives no suggestion

An unknown subcommand produced no "did you mean", no list of valid commands and no pointer to help.

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

Severitywarn
KindHeuristic. A pattern match: a prompt to look, not a verdict.
Modeax-check probe-cli
Applies toCommand-line programs, run as a subprocess
Pattern tagserror-recovery, discovery
Fix in one lineOn an unknown command, suggest the closest valid command and list the valid ones.

When given a subcommand that does not exist, the program gave no “did you mean”, no list of valid commands and no pointer to help. This is the moment an agent most needs a map, and the program leaves it with nothing.

What it checks

The rule looks only at the unknown-subcommand probe, which runs <cmd> axcheck-unknown-subcommand when you pass --probe errors. It runs only when the help output lists subcommands, because a CLI with no subcommands may take the word as an ordinary argument. It fires when the output contains none of these: a “did you mean” style suggestion, a pointer to help, or at least two of the commands that help lists.

Why it matters

Agents often start with a guess at a command name taken from memory or from stale instructions. When the guess is wrong, a good CLI tells them what is available. The Command Line Interface Guidelines describe discoverable CLIs as ones that “suggest what command to run next, suggest what to do when there is an error.” A suggestion turns a dead end into one more step. Without it the agent must try --help, parse it, and retry, if it thinks to do so at all.

This rule is narrower than AXC-C004. AXC-C004 asks whether any error names a next step. This rule asks whether the unknown-command case lists the real commands.

How to fix

On an unknown command, print the closest valid command and list the valid ones, or at least point to --help. Keep it short.

Example

Before

$ invoicer axcheck-unknown-subcommand </dev/null; echo $?
error: command failed
1

After

$ invoicer axcheck-unknown-subcommand </dev/null; echo $?
error: unknown command "axcheck-unknown-subcommand".
Valid commands: create, list, show, export, void.
Run: invoicer --help
2

For a near miss, a suggestion is better still:

$ invoicer crate
error: unknown command "crate". Did you mean "create"?

A Python fix using the standard library:

import difflib
close = difflib.get_close_matches(cmd, COMMANDS, n=1)
if close:
    print(f'error: unknown command "{cmd}". Did you mean "{close[0]}"?', file=sys.stderr)
print("Valid commands: " + ", ".join(COMMANDS), file=sys.stderr)

How ax-check detects it

ax-check parses the help output for the names of the subcommands. It then checks the unknown-subcommand output for “did you mean” (or “perhaps you meant”, “maybe you meant”, “similar command”), for help or --help, for “available commands”, “valid commands” or a “commands:” heading, or for the names of at least two real subcommands. It never invents or mistypes one of your real subcommands to test for suggestions. Some CLIs auto-correct a typo and run the corrected command, which would cause a real action, so ax-check always uses the fixed name axcheck-unknown-subcommand. This means it cannot test your “did you mean” logic for near misses. It only checks that the far-miss case is helpful.

To reproduce by hand: invoicer axcheck-unknown-subcommand </dev/null; echo $?.

A CLI whose help does not list its subcommands in a form ax-check can parse is not tested at all, so the rule can miss real problems. Silence it with --disable AXC-C005 if it does not apply.

Safety note: The error probes this rule needs are opt-in: run with --probe errors. Without it the rule is not checked, and the report lists it as not checked. Argument parsers normally reject an unknown subcommand, an unknown flag or a missing value before doing any work, but a program that does not validate its arguments will do its ordinary work instead. 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.