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 has one fixed Managed layout: package payloads live once under pool/, while dists/ contains metadata-only client views. The complete repository directory is the unit to serve, copy, or publish.

Plain mode

sow create writes indexes next to existing packages and leaves every unrelated file unchanged:

/srv/offline/
├── blackbox_exporter-0.28.0-1.x86_64.rpm
├── libpq5_18.3-1.pgdg12+1_amd64.deb
├── repodata/
│   ├── <sha256>-primary.xml.gz
│   ├── <sha256>-filelists.xml.gz
│   ├── <sha256>-other.xml.gz
│   └── repomd.xml
├── Packages
├── Packages.gz
└── repo_complete                         # only with --pigsty

Flat RPM metadata uses a bare package basename; flat DEB metadata uses ./<filename>. While a build is active, .sow-plain-stage-* contains private generated output. Plain has no durable journal or recovery state; a later create discards stale reserved temporary paths and rebuilds. Never serve or copy those temporary paths.

Reference

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

This section is the stable contract for configuration fields, package references, paths, exit codes, JSON, platforms, and integrations. CLI syntax and state transitions live in Commands; use Get Started for the operating model.

Output examples show shape; identifiers, paths, hashes, timestamps, and counts vary by workspace. The built-in sow help remains the exact syntax authority.

sow.yml Reference

The complete configuration schema: workspace, repository, distribution, membership policy, signing, and publication targets.

Package References

The five ways to name a package on the command line, how ambiguity is resolved, and which forms rm, show, and where accept.

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.

Platforms & Integrations

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

This page defines the environments SOW ships for, the storage semantics it requires, and the exact scope of its automated integrations. Repository generation happens inside the SOW binary; a real package manager remains the final check for a deployed repository.

Release targets

Operating system	`amd64`	`arm64`	Artifact
Linux	yes	yes	archive, RPM, DEB
macOS	yes	yes	archive
Windows	no	no	not supported

Release binaries use CGO_ENABLED=0 and require no language runtime. The 0.4.0 artifacts were built with Go 1.27.0; the source module requires Go 1.27.0 or newer. Archives include README.md, CHANGELOG.md, and the Apache-2.0 LICENSE; Linux packages install the same license with the binary. Use sow version to print the product version, target OS/architecture, and build toolchain.