Files
tty7/docs
l0ng-ai 74e8fdb5a7 docs: say what --json does when a verb fails
The flag's row promised "one JSON object on stdout" and stopped there.
Running the error paths, most verbs print nothing on stdout at all —
`capture %999`, `procs %999`, `tab close @99`, `ws rm nosuch`,
`tab rename @99 x` each exit 1 with the message on stderr and an empty
stdout. A reader that parses stdout without checking the exit code first
gets an empty string where it expected an object.

Two verbs deliberately do the opposite, because there the bad news is the
answer: `pane close` prints `failed[]` and `wait` prints the state it
gave up in. Both are already pinned by tests, so this only writes down
the rule they are exceptions to.

`run` looked like a third exception and is not: a child exiting nonzero
is the verb succeeding. Checked rather than assumed —
`run --json -- sh -c 'exit 3'` prints its object and exits 3 — and the
row now says so, since that is the case most likely to be misread as a
failure that kept its JSON.
2026-08-16 11:27:30 +08:00
..