ax-check rule

AXC-C008: No dry-run flag documented

Help documents no --dry-run or equivalent, so an agent cannot rehearse a change before making it.

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

Severityinfo
KindHeuristic. A pattern match: a prompt to look, not a verdict.
Modeax-check probe-cli
Applies toCommand-line programs, run as a subprocess
Pattern tagsdry-run, approval
Fix in one lineIf the CLI changes anything, add --dry-run that prints what would happen without doing it.

The help text documents no --dry-run or similar flag. If the command changes anything, an agent cannot rehearse the change and show a person what would happen before it happens.

What it checks

ax-check reads the help output. The rule fires when the text mentions none of: --dry-run, --dryrun, --what-if, --whatif, --plan, --preview, --noop or --simulate. If no help probe works, this rule does not run. It is an info finding because many commands only read data, and a read-only tool has nothing to preview.

Why it matters

Agents are often asked to act under human approval. A dry run gives the approver something concrete to read. The Command Line Interface Guidelines list “-n, –dry-run: Dry run. Do not run the command, but describe the changes that would occur if the command were run.” Cloudflare’s documentation for its cf CLI says: “Add –dry-run to print the request as JSON without sending it. Dry runs need no credentials.” (vendor documentation). The ability to run without credentials means an agent can prepare a change before anyone grants it access.

Our guide on approval as a workflow explains why a rehearsal step belongs in the design of agent tools, not only in the interface.

How to fix

If the CLI changes anything, add --dry-run. It should print what would change, in the same format as the real run where possible, and exit 0 without making the change. Document it in --help.

Example

Before

$ invoicer void --help
Usage: invoicer void <id>

Marks an invoice as void.

After

$ invoicer void --help
Usage: invoicer void <id> [--dry-run]

Marks an invoice as void.

Options:
  --dry-run   Print what would change and exit without changing it
$ invoicer void 1042 --dry-run
Would void invoice 1042 (customer: Acme Ltd, total: 120.00).
No changes made.

A Python fix:

parser.add_argument("--dry-run", action="store_true",
                    help="print what would change and exit without changing it")
...
if args.dry_run:
    print(f"Would void invoice {inv.id} ({inv.customer}, total {inv.total}).")
    print("No changes made.")
    return 0

How ax-check detects it

This is a text search over the help output for the spellings above. A bare -n is not recognised, so document the long form too. It does not run a dry run, and it does not judge whether your command changes anything. A read-only CLI will therefore get this finding even though it needs no dry run. It is info severity for that reason.

Known false negatives: a help text that mentions “preview” in an unrelated sentence. Silence the rule with --disable AXC-C008 for read-only tools.

To reproduce by hand: invoicer --help </dev/null | grep -Ei 'dry-?run|what-?if|plan|preview|noop|simulate'.

Safety note: This rule reads help text only, from the default --help probe. 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.