ax-check rule

AXC-C006: No machine-readable output flag

Help documents no --json, --format json or similar flag, so an agent must parse text meant for people.

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 tagsnon-interactive, docs-for-agents
Fix in one lineAdd --json (or --format json) and document it in --help.

The help text documents no flag for JSON output. An agent that wants the result as data has to read text that was laid out for human eyes, which breaks when the layout changes.

What it checks

ax-check reads the output of the help probe (--help, falling back to -h, and to help with --probe help-word). The rule fires when the help text mentions none of: --json, --format json, --format=json, --output json, -o json, --jsonl, --ndjson or --porcelain, and no documented flag offers json as a choice. If no help probe works, this rule does not run, and AXC-C009 reports the missing help instead.

Why it matters

Tables, colours and aligned columns are for people. A script or an agent needs fields it can address by name. The Command Line Interface Guidelines say: “Display output as formatted JSON if –json is passed.” Cloudflare’s documentation for its cf CLI says that its output contract puts the result on stdout as JSON (vendor documentation).

Missing machine output is also a documented pain point. cloudflare/cf issue #105 is titled “Output for scripts and agents: empty stdout with exit 0, –version not machine-readable, agent detection changes nothing”. The --version part was later fixed. The issue is context, not a measurement of how common the problem is.

How to fix

Add --json (or --format json) and list it in --help. With the flag, write only JSON to stdout and send all other messages to stderr. See AXC-C007, which checks that the JSON really parses.

Example

Before

$ invoicer list --help
Usage: invoicer list [options]

Options:
  --status <s>   Filter by status
  --limit <n>    Maximum rows
$ invoicer list
ID      CUSTOMER      TOTAL     STATUS
1042    Acme Ltd      120.00    paid
1043    Brightside    80.50     open

After

$ invoicer list --help
Usage: invoicer list [options]

Options:
  --status <s>   Filter by status
  --limit <n>    Maximum rows
  --json         Print the result as JSON on stdout
$ invoicer list --json
[{"id":1042,"customer":"Acme Ltd","total":"120.00","status":"paid"},
 {"id":1043,"customer":"Brightside","total":"80.50","status":"open"}]

A Node fix:

if (opts.json) {
  process.stdout.write(JSON.stringify(rows) + '\n');
} else {
  printTable(rows);
}

How ax-check detects it

This is a text search over the help output. It looks for the listed flag spellings anywhere in the text, including in prose. It does not check that the flag works. With --probe json, AXC-C007 checks that the output parses; without it, AXC-C013 reports that the output was not verified.

Known false positives: a CLI whose output is already machine-readable by default, for example one that always prints JSON, and a CLI that has no meaningful output. Known false negatives: help text that mentions --json in an unrelated sentence. Silence the rule with --disable AXC-C006 when it does not apply.

To reproduce by hand: invoicer --help </dev/null | grep -Ei 'json|jsonl|ndjson|porcelain'.

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

  • Guideline: Command Line Interface Guidelines, clig.dev. https://clig.dev/ . Says to display output as formatted JSON if --json is passed.
  • Vendor documentation: Use cf with coding agents, Cloudflare, updated 2026-09-29. https://developers.cloudflare.com/cf/agents/ . Documents an output contract with the result on stdout as JSON.
  • Vendor issue: cloudflare/cf issue #105, “Output for scripts and agents: empty stdout with exit 0, –version not machine-readable, agent detection changes nothing”. https://github.com/cloudflare/cf/issues/105 . Context only; the --version part was later fixed.

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.