Skip to content

ADR-185: CLI output contract: structured output for people, JSON for machines

Summary

  • Decided: Every command in ways and attend prints structured output for a person by default, through the shared agent-fmt formatter, and prints one JSON document on stdout under --json, with diagnostics on stderr. A debug rendering never reaches stdout. Where a resolved value differs from the stored one, --json shows what the file says and --json --effective shows the resolved state, and only the first can be fed back to an apply command. A command that shows a configuration object has a partner that accepts the same JSON back. Exit 0 means done, 1 means a failure the command reports, and 2 means bad usage; a refusal to act gets a code that callers can tell apart from failure. A note dated 2026-10-10 fixes the JSON shape of a refusal as an error object with a kind, plus a message.
  • Trades away: Only three of forty commands met the contract when it was written, and the rest convert during ordinary work. The split between effective and stored values is one more flag to explain. agent-fmt becomes a dependency of every output path in ways. The record rejected JSON by default, YAML for round trips, and leaving output to each command.
  • One-way? No. The record calls it reversible: each command converts on its own, and nothing depends on the order.
  • Probes: Not confident (human-default): Should the default output be written for people rather than for scripts? Yes or no. Not confident (round-trip): Should every command that shows a configuration object have a partner that takes the same JSON back? Yes or no.
  • Inversion: At one end each command prints whatever its author chose. At the other every command speaks only JSON. This decision sits between them: a formatted view for people by default, and one fixed JSON document for scripts on request.

Context

ways config show prints a Rust debug rendering of the config struct. Three of the binary's forty verbs take --json. attend renders tables through agent-fmt while ways prints ad hoc lines. ADR-111 chose the argument parser and said nothing about output, so every verb has decided for itself.

ADR-184 adds verbs whose output an operator reads to decide what to activate, and whose output a script reads to decide what to do next. Both readers need a stable form.

Decision

Every verb in ways and attend renders for a person by default, through agent-fmt, and renders JSON under --json. A debug rendering never reaches stdout.

  1. Human output is structured: tables for lists, labeled rows for records, color where the terminal supports it and none where it does not. The formatter already in the workspace is the one renderer.

  2. --json emits one document on stdout and nothing else there. Diagnostics go to stderr. The document's shape is the verb's contract, and a change to it is a change to the verb.

  3. Two views where a resolved value differs from a stored one. --json emits what the file says. --json --effective emits the resolved state with defaults applied. Only the first is accepted back by an apply verb. Round-tripping the effective view would freeze every default at its current value.

  4. Round trip. A verb that shows a configuration object has a partner that accepts the same JSON back. The pair is the test: show, apply, show again, byte-equal.

  5. Exit codes carry the verdict. Zero for done, one for a failure the verb reports, two for bad usage. A verb that refuses to act, such as reconcile at a real directory, uses a code the caller can distinguish from failure.

Reversibility: reversible. Each verb converts on its own; a verb not yet converted is a defect against this contract, and nothing depends on the order.

Consequences

Positive

  • An operator reads a table; a script parses a document. Neither has to parse the other's form.
  • The bootstrap in ADR-184 shows the plan per target in the same renderer attend uses, which people already read.
  • Round-trip pairs make configuration editable by tools without hand-editing YAML.

Negative

  • Forty verbs, three converted. The sweep is spread over ordinary work, and the contract holds before the sweep completes.
  • Effective-versus-stored is one more flag to explain.

Neutral

  • agent-fmt becomes a dependency of every output path in ways, as it already is in attend.
  • The config verbs in ADR-184 are the first converted, since they are new.

Alternatives Considered

  • JSON by default, human on a flag. Rejected: the first reader of every verb is the operator at the terminal, and a guiding Claude reading the output prefers the labeled form too.
  • A third format such as YAML for round trips. Rejected: one machine format keeps the pair test simple, and the apply verb writes the config file's YAML.
  • Leave output to each verb. The status quo. Rejected by the defect that opened this decision.

Note, 2026-10-10: the shape of a refusal under --json

Appended after acceptance; nothing above is changed. It writes down how a refusal reads under --json, which items 2 and 5 left open.

  • A verb that refuses under --json still emits one document on stdout: {"error": {"kind": "<kind>", ...}, "message": "<one line>"}. kind is a snake_case tag, and any other fields in error belong to that kind. A caller tells a refusal from a result by the error key, and branches on error.kind. The person's wording still goes to stderr.
  • Exit 2 means usage. A usage refusal under --json has error.kind set to usage and no other fields: {"error": {"kind": "usage"}, "message": "<why>"}. Exit 1 is a failure the verb reports, with its own kind.
  • An argument error the parser raises itself, such as an unknown flag or two flags that conflict, exits 2 in the parser's own text, with no JSON document. A caller that sees exit 2 and no document on stdout has met one.
  • A benign miss keeps its exit code. attend inbox <id> --json for a message already reaped exits 0 with {"error": {"kind": "not_found"}, ...}.

attend's message verbs follow this from PR #900: send, reply, inbox, join and channels.