Output contracts

Response-producing CLI commands write exactly one JSON object to stdout by default. Pass --yaml for YAML. Diagnostic logs go to stderr and are controlled by RUST_LOG, -v, and -vv.

Response envelope

CLI and documented HTTP handler success and error responses use schema_version, ok, and type, plus command-specific fields. Output excerpts include encoding, byte ranges, and total byte counts; log paths identify complete retained logs.

{"schema_version":"0.2","ok":true,"type":"wait","job_id":"<id>","state":"exited","exit_code":0,"stdout":"done\n","stderr":"","encoding":"utf-8-lossy","stdout_range":[0,5],"stderr_range":[0,0],"stdout_total_bytes":5,"stderr_total_bytes":0,"updated_at":"2026-07-20T00:00:00Z"}

Boundaries

Generated completions, MCP stdio protocol, and Clap help/version output are not response envelopes. Router-level unmatched HTTP paths and methods are also outside this contract.

The serve command emits a JSON error envelope for startup configuration failures such as an unsafe bind, a missing token for a non-loopback bind, or a wildcard CORS origin. MCP startup errors are outside the response-envelope contract.

Raw and compressed output

Inline compression can reduce response size, but raw stdout, stderr, ranges, totals, encoding, and retained log paths remain canonical.