Exit Codes

Mon, 01 Jan 0001 00:00:00 +0000

Every sow command exits with one of seven codes. They are stable, they are the same for every command, and they are meant to be branched on in scripts — the distinction between “this failed” and “this was correctly refused” is the whole point of having more than one nonzero code.

Code	Meaning
`0`	Complete success, or an idempotent no-op
`1`	Runtime I/O, parser, renderer, or unknown internal error
`2`	Usage, workspace discovery, or configuration error
`3`	Partial success: at least one item committed, at least one failed
`4`	Write lock unavailable — held and `--no-wait`, or the timeout expired
`5`	Integrity or recovery error, or `check` judged the result not deliverable
`6`	Expected rejection: conflict, protected, no match, incompatible architecture

Human-readable results go to stdout; warnings and diagnostics go to stderr. Each code has a stable message prefix on stderr, and a matching class in JSON output:

JSON Output

Mon, 01 Jan 0001 00:00:00 +0000

Every command that produces data accepts --json. The output is a single line on stdout carrying a versioned envelope, so you can pipe it straight into jq without worrying about which command produced it.

sow status --json

{"schema":"sow.cli/v1","command":"status","ok":true,"repository":"pigsty","operation":null,
 "result":{"repository":"pigsty","status":"clean","ready_to_copy":true,"desired_revision":4,
 "built_generation":"00000000000000000004","dirty_dists":[],"dirty_reasons":[],"pending":{"count":0,"bytes":0},
 "recent_operation":{"id":"8632724976452398569","kind":"add","state":"done",
 "created_at":"2026-08-04T04:07:17.665377Z","updated_at":"2026-08-04T04:07:18.293848Z"},
 "repository_locked":false},"errors":[]}

(Line-wrapped here for readability; the real output is one line.)

The envelope

Field	Type	Meaning
`schema`	string	Always `sow.cli/v1`. Check it before parsing anything else.
`command`	string	The command as invoked, including the subcommand: `add`, `repo ls`, `config show`.
`ok`	bool	`true` when `errors` is empty. Equivalent to exit code `0`.
`repository`	string or null	The selected repository, or `null` for workspace-wide and plain-mode commands.
`operation`	string or null	The operation ID for write commands, `null` for read-only ones.
`result`	object or null	Command-specific payload, described below.
`errors`	array	Zero or more `{code, class, message}` objects.

All seven fields are always present. result is null when the command failed before meaningful work — an unknown flag, discovery failure, or invalid configuration before a Repository was selected, for example. Committed partial results and diagnostic results from check or rm --check are preserved even when the command exits nonzero.

output on SOW

Exit Codes

JSON Output

The envelope