---
title: 'P2: Structured, Parseable Output'
description: 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…
url: https://anc.dev/p2
dateModified: '2026-11-09'
---

# 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

**MUST:**

- Structured-output CLIs offer at least one machine-readable format selectable via `--output`, with `json` and `jsonl`
  as canonical values; `text` is the default human-facing form. The format selection threads through every output path,
  so a single invocation never mixes formats.
- Data goes to stdout. Diagnostics, progress indicators, and warnings go to stderr. An agent consuming JSON from stdout
  must never encounter an interleaved progress message.
- Exit codes are structured and documented. Codes 77 and 78 follow BSD `sysexits.h` (`EX_NOPERM`, `EX_CONFIG`); the
  broader sysexits range is intentionally not mandated to keep the surface small:

  | 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. A `schema` subcommand (or a
  `--schema` flag on each data-emitting subcommand) is the recommended surface; an introspection command under another
  name satisfies the requirement when the tool's `--help` documents it as the command that describes the output's
  structure (`kubectl explain`, which prints the fields of the resources `kubectl get -o json` returns). 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.
- *(Applies when: CLI emits structured output.)* The same schema is also exported to a stable file path in the source
  repo (e.g., `schema/<command>.json`), so consumers pin against it at install or CI time without invoking the tool. The
  runtime schema is the runtime contract; the file is the build-time contract.
- `--json` and `--jsonl` are accepted as aliases for `--output json` and `--output jsonl`. The `--output` enum remains
  the canonical surface for the format MUST above; a CLI shipping only the short forms still satisfies that MUST through
  the alias path.

**MAY:**

- Additional output formats (CSV, TSV, YAML) beyond the core three. The core three remain mandatory.
- A `--raw` flag for unformatted output suitable for piping to other tools.

## 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-json-output`, `p2-structured-output`, `p2-output-module`, `p2-structured-exit-codes`,
`p2-json-errors`, `p2-schema-print`, `p2-consistent-envelope`, `p2-schema-file`, `p2-json-aliases`, `p2-more-formats`,
`p2-raw-flag`. Run `anc audit --principle 2 .` against the CLI under test to see each.
