The --json flag's own help text points at JSON_MODE_SPEC.md, and the file is referenced 18 times across cmd/, including as the authority for the closed error-code set and the streaming shape. The file does not exist in the repository.
$ grep -rn "JSON_MODE_SPEC" --include=*.go . | wc -l
18
$ ls JSON_MODE_SPEC.md docs/JSON_MODE_SPEC.md
ls: cannot access 'JSON_MODE_SPEC.md': No such file or directory
ls: cannot access 'docs/JSON_MODE_SPEC.md': No such file or directory
For an interface aimed at scripting, that document is the product surface — someone told to read it by the help output has nowhere to go.
Two things it should pin down, both of which are surprising and neither of which is discoverable from the output alone:
- Success is not the exit status. It is the absence of an
error key. status --json emits a complete, valid status payload and still exits non-zero whenever the instance is not running.
- Streaming versus single-object commands. Which commands emit NDJSON stage events (
{stage, state, detail, error, result}) and which emit one object, and that the terminal event of a stream is stage: "complete".
Worth also documenting jsonContract and what a consumer should do when it does not match the value it was built against.
The
--jsonflag's own help text points atJSON_MODE_SPEC.md, and the file is referenced 18 times acrosscmd/, including as the authority for the closed error-code set and the streaming shape. The file does not exist in the repository.For an interface aimed at scripting, that document is the product surface — someone told to read it by the help output has nowhere to go.
Two things it should pin down, both of which are surprising and neither of which is discoverable from the output alone:
errorkey.status --jsonemits a complete, valid status payload and still exits non-zero whenever the instance is not running.{stage, state, detail, error, result}) and which emit one object, and that the terminal event of a stream isstage: "complete".Worth also documenting
jsonContractand what a consumer should do when it does not match the value it was built against.