P2: Structured, Parseable Output

Definition

CLI tools MUST separate data from diagnostics and offer machine-readable output formats. Mixing status messages with data forces agents into fragile regex extraction that breaks on any format change.

Why Agents Need It

An agent calling a CLI needs three things from each invocation: the data, the error (if any), and the exit code. When data goes to stdout, diagnostics go to stderr, and errors carry machine-readable fields, the agent parses the result reliably without heuristics. Mix these channels or ship human-formatted output only, and the agent falls back to best-effort text parsing that fails unpredictably across versions, locales, and edge cases: silently at first, catastrophically later.

Requirements

Code	Meaning
0	Success
1	General command error
2	Usage error (bad arguments)
77	Authentication / permission error
78	Configuration error

When --output json is active, errors are emitted as JSON (to stderr) with at least error, kind, and message fields. A plain-text error in a JSON run breaks the consumer's parser on the only shape it was told to expect.
(Applies when: CLI emits structured output.) The output schema is exposed at runtime via a schema subcommand or a --schema flag on each data-emitting subcommand. The schema identifies its format (canonical recommendation: JSON Schema 2020-12, the same dialect OpenAPI 3.1 uses), so an agent reading the schema loads the right validator without parsing prose. A consumer asking "what shape am I about to receive?" gets a machine-readable answer in one call.

SHOULD:

JSON output uses a consistent envelope (a top-level object with predictable keys) across every command so agents can rely on the same shape. Passthrough tools whose value is the user's own JSON (jq, dasel) are exempt; the envelope applies to commands that emit tool-defined data.
(Applies when: CLI emits structured output.) The same schema is also exported to a stable file path (e.g., schema/<command>.json in the release artifact). Runtime discovery covers ad-hoc inspection; the file path lets CI and static-analysis consumers pin the schema without invoking the tool.
--json and --jsonl are accepted as aliases for --output json and --output jsonl. The --output enum remains the canonical surface for p2-must-output-flag; a CLI shipping only the short forms still satisfies the canonical MUST through the alias path.

Evidence

Rust reference implementation:

OutputFormat enum with Text, Json, Jsonl variants deriving ValueEnum.
OutputConfig struct with format, use_color, and quiet fields threaded through every output-producing function.
serde_json in Cargo.toml.
No println! in src/ outside the output module: every print goes through OutputConfig.
Exit-code constants or match arms mapping error variants to distinct numeric codes.
eprintln! (or an equivalent diagnostic macro) for every diagnostic line.

Anti-Patterns

println! scattered across handlers instead of routing through the output config.
A single exit code (1) for everything: agents cannot distinguish auth failures from config errors.
Status lines ("Fetching data…") printed to stdout where they contaminate JSON output.
process::exit() in library code, bypassing structured error propagation.
Human-formatted tables as the only output mode with no JSON alternative.

Measured by audit IDs p2-output-json, p2-output-format, p2-stderr-diagnostics. Run anc audit --principle 2 . against the CLI under test to see each.