Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

CLI JSON Output Envelope

Status: stable contract as of P3.3. Crate: yanshi-cli. Wire schema: yanshi.cli/1. Reference implementation: yanshi_cli::json_envelope::CliJsonEnvelope.

yanshi CLI commands that support automation expose a --format json-envelope (or --output json-envelope) mode that emits the canonical envelope below. The envelope is the v1 contract every new JSON output mode follows; existing raw-JSON modes (--format json) remain available for backward compatibility until v1.0.

Envelope shape

{
  "version": "yanshi.cli/1",
  "command": "doctor",
  "result": { /* per-command payload */ },
  "errors": []
}

The four fields are closed — adding a fifth top-level field is a breaking change that bumps version to yanshi.cli/2.

FieldTypeNotes
versionstringWire schema discriminator. Always yanshi.cli/N. Producers and consumers MUST treat unknown versions as opaque.
commandstringSubcommand path the operator typed, space-separated ("doctor", "workflow validate", "marketplace install"). Lets multiplexed log captures be parsed without inspecting the payload.
resultobject | array | nullPer-command payload. Each command documents its own result schema and tracks it under its own stability tier. May be null for metadata-only outputs.
errorsarray of stringsZero-or-more single-line user-actionable error messages. Never null — successful runs emit []. Structured error codes belong inside result when the per-command schema needs them.

Producer contract

#![allow(unused)]
fn main() {
use yanshi_cli::json_envelope::CliJsonEnvelope;

// Success path: any Serialize payload, no errors.
let envelope = CliJsonEnvelope::ok("doctor", &report);
println!("{}", serde_json::to_string_pretty(&envelope)?);

// Partial success with operator-visible warnings/errors:
let envelope = CliJsonEnvelope::with_errors(
  "workflow validate",
  &report,
  vec!["missing parameter 'foo'".to_string()],
);
}

A command that surfaces only errors (no usable result) still emits the full envelope — result is set to the per-command “empty” shape (e.g. an empty list, or a sentinel {"failed": true} block). Returning null is allowed for commands where the absence of data is meaningful.

Consumer contract

  • Parse against version first. Reject any envelope whose version you don’t know.
  • errors is always present. Treat an empty errors array as a successful run; the process exit code carries the same signal but consumers parsing piped JSON shouldn’t have to track exit codes separately.
  • Tolerate additive result fields. Per-command payloads follow the P0.3 additive-field contract: every consumer must ignore unknown keys inside result so future additions don’t break old parsers.
  • Don’t rely on key order. Serialization order is not part of the contract — sort keys before comparing.

Coverage matrix

CommandBare JSONEnvelopeNotes
yanshi doctor--format json--format json-envelopeFirst migration; envelope wraps DoctorReport. The bare-JSON form is preserved for the in-process /v1/diagnostics handler.
yanshi workflow validate--format jsonn/a (planned)Per-node permission report under result; envelope migration tracked as a P3.3 follow-up.
yanshi workflow resume-plan--format jsonn/a (planned)ResumePlan payload.
yanshi eval run--format jsonn/a (planned)EvalReport payload.
`yanshi harness runlistinspect`--output json / stream-json
yanshi llm models(text only today)n/a (planned)Add --output json-envelope alongside text.
yanshi mcp list-tools | list-resources | call-toolpartialn/a (planned)The call-tool result currently prints raw JSON; needs the envelope plus a tool_call_id field in result.
yanshi plugin list | install | inspecttext onlyn/a (planned)Auto-completion-friendly output needed.
yanshi rag search | evalpartialn/a (planned)rag eval already emits a structured EvalReport; envelope migration adds the wrapping.
yanshi trace list | replay | showtext onlyn/a (planned)Auto-tooling consumers want JSON.
yanshi workflow run | list | cancel | graph | logstext onlyn/a (planned)Server-backed; depends on P2.5 --server plumbing.

Each “planned” row lands as its own commit per the P3.3 follow-up checklist in TODOs.md. The envelope itself is stable today.

Versioning policy

  • yanshi.cli/1 is the current wire version.
  • A version bump is required for: removing or renaming a top-level envelope field; changing the shape of errors; reinterpreting command semantics.
  • A version bump is not required for: adding optional fields inside per-command result; adding a new command; adding a new version value to the consumer matrix.