Reference on SOW

sow.yml Reference

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

sow.yml is the single configuration file of a managed workspace. It sits at the workspace root, declares which repositories and distributions exist, and holds the membership policy and signing settings that every build applies. Plain mode (sow create) never reads it.

This page lists every field the parser accepts. Anything not listed here is rejected — there are no undocumented keys and no keys reserved for future use.

How the file is read

SOW parses sow.yml with a strict decoder. Practically, that means:

Package References

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

sow rm, sow show, and sow where all take a PACKAGE argument. This page defines what you may write there. The same grammar applies to all three commands; only the handling of an ambiguous name differs.

Nothing here applies to sow add, which takes filesystem paths, not references.

The five forms

Form	Example	Matches
Content digest	`sha256:d06d7f23b9cf...b98b1229`	Exactly one package object
RPM coordinate	`rpm:pev2-0:1.23.0-1.noarch`	Exactly one RPM
DEB coordinate	`deb:libpq5=18.3-1.pgdg12+1:amd64`	Exactly one DEB
Filename	`pev2-1.23.0-1.noarch.rpm`	The package stored under that filename
Bare name	`pev2`	Every version and architecture of that name

The first three are exact: they name one object and either hit it or fail. The last two are conveniences that may match more than one object.

Repository Layout

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

SOW’s on-disk layout is fixed. There is no path: setting, no template, and no way to relocate a repository — every path is derived from the workspace root, a validated name, and a constant relative segment. This page is the complete map, so you know what to serve, what to copy, and what to keep private.

Plain mode

sow create writes indexes next to the packages and touches nothing else. The directory you point it at stays a flat repository: packages and metadata share one level.

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":4,"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 only when the command failed before it could produce anything — an unknown flag, for example.

Compatibility

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

SOW writes standard rpm-md and Debian archive metadata, so the question is not whether a client can read it but which clients have actually been verified against it. This page lists the tested matrix, the platforms the binary runs on, and the handful of constraints that will bite you if you ignore them.

Package manager clients

Every row below was exercised end to end against a repository built by SOW: refresh the index, list packages, and install one.