Commands on SOW

sow create

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

sow create turns a directory that already contains .rpm and .deb files into a flat repository by writing indexes next to the packages. It is the whole of Plain mode: no sow.yml, no SQLite, no Workspace discovery. This page covers the one-pass scan contract, the --pigsty completion gate, and RPM signing with --sign-with.

Synopsis

sow create [DIR] [-j N] [--pigsty] [-S KEY [--overwrite]] [-T DUR | -N] [--json]

DIR defaults to the current directory.

sow init

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

sow init creates the root sow.yml and the private .sow/ state directory that make a directory a Workspace. It is also the convergence command for a config you wrote by hand: if sow.yml already declares Repositories and Dists, init materializes the ones that don’t exist yet and leaves the finished ones alone.

Synopsis

sow init [DIR] [--json]

DIR defaults to the current directory. init takes no -C/--workdir — the positional argument already names the target unambiguously.

sow config

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

sow config has two read-only subcommands. config check is the full preflight over sow.yml — run it after every hand edit and in CI. config show prints the configuration SOW actually computed, which is where you confirm that defaults, inherited architectures and normalized aliases resolved the way you expected.

Neither subcommand creates directories, touches a database, or corrects your file.

Synopsis

sow config check [-C DIR] [--json]
sow config show [--all] [-C DIR] [-r NAME] [-d NAME]... [--json]

sow help config lists both.

sow repo

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

A Repository owns one pool/, one dists/, one SQLite database and one private state directory. It is the boundary of locking, transaction recovery, Generation numbering and Changesets — nothing is deduplicated across Repositories and no cross-Repository commit is atomic. sow repo manages that boundary.

Synopsis

sow repo ls [-C DIR] [--json]
sow repo new NAME [-C DIR] [-T DUR | -N] [--json]
sow repo show [NAME] [-C DIR] [-r NAME] [--json]
sow repo migrate [NAME] [--abort] [-j N] [-C DIR] [-r NAME] [-T DUR | -N] [--json]
sow repo rm NAME [-f|--force] [-C DIR] [-T DUR | -N] [--json]

Naming

A Repository name must match [a-z0-9][a-z0-9._-]* and may not be ., .., .sow, pool, dists, or collide with a Workspace reserved file.

sow dist

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

A Dist is a named set of packages in exactly one format (rpm or deb) inside one Repository. It is what a client points at. A Repository can hold RPM and DEB Dists side by side; they share one pool/ but render into completely separate dists/ subtrees.

Synopsis

sow dist ls [-C DIR] [-r NAME] [--json]
sow dist new NAME --format rpm|deb [-C DIR] [-r NAME] [-T DUR | -N] [--json]
sow dist show NAME [-C DIR] [-r NAME] [--json]
sow dist rm NAME [-f|--force] [-C DIR] [-r NAME] [-T DUR | -N] [--json]

Naming

Dist names follow the same rule as Repository names: [a-z0-9][a-z0-9._-]*, excluding ., .., .sow, pool and dists.

sow add

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

sow add is the main write path. It parses the packages you point at, derives their format and architecture from the package headers, applies the Dist’s membership policy, and — unless you pass --skip — rebuilds every affected index before it returns. When the command exits 0, clients can already see the new packages.

Synopsis

sow add PATH... [-R|--recursive] [--skip] [-j|--jobs N] [-C|--workdir DIR] [-r|--repo NAME] [-d|--dist NAME]... [-T|--timeout DUR | -N|--no-wait] [--json]

Options

Flag	Description	Default
`-R, --recursive`	Descend into subdirectories of a `PATH` directory	off (top level only)
`--skip`	Update Desired state only; do not build	off
`-j, --jobs N`	Parallel workers for parsing, hashing and rendering	logical CPU count
`-C, --workdir DIR`	Workspace discovery start directory	current directory
`-r, --repo NAME`	Select a repository	selection rules
`-d, --dist NAME`	Select a distribution; repeatable	selection rules
`-T, --timeout DUR`	Maximum lock wait; `0` waits indefinitely	`0`
`-N, --no-wait`	Fail immediately when the lock is held	false
`--json`	Emit the versioned JSON envelope	false

Inputs and targets

PATH can be a file or a directory. A directory is scanned top level only unless you pass -R.

sow rm

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

sow rm takes packages out of the Desired Membership of the Dists you select and, by default, rebuilds the affected indexes immediately. It does not delete bytes from pool/ — membership and content are separate concepts, and reclamation is the separate conservative sow gc operation.

Synopsis

sow rm PACKAGE... [-c|--check] [--skip] [-j|--jobs N] [-C|--workdir DIR] [-r|--repo NAME] [-d|--dist NAME]... [-T|--timeout DUR | -N|--no-wait] [--json]

Options

Flag	Description	Default
`-c, --check`	Preview only; compute and print the plan without writing anything	off
`--skip`	Update Desired state only; do not build	off
`-j, --jobs N`	Parallel workers	logical CPU count
`-C, --workdir DIR`	Workspace discovery start directory	current directory
`-r, --repo NAME`	Select a repository	selection rules
`-d, --dist NAME`	Select a distribution; repeatable	selection rules
`-T, --timeout DUR`	Maximum lock wait; `0` waits indefinitely	`0`
`-N, --no-wait`	Fail immediately when the lock is held	false
`--json`	Emit the versioned JSON envelope	false

--check and --skip are mutually exclusive:

sow ls

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

sow ls is a read-only query over Package Objects and Dist Membership. It shows what each selected Dist should contain and whether that membership is present in the current Built Generation.

Synopsis

sow ls [-C|--workdir DIR] [-r|--repo NAME] [-d|--dist NAME]... [--json]

Flag	Meaning	Default
`-C, --workdir DIR`	Workspace discovery start directory	current directory
`-r, --repo NAME`	Select a Repository	selection rules
`-d, --dist NAME`	Select a Dist; repeatable	selection rules
`--json`	Emit the `sow.cli/v1` envelope	false

There is no --pool, --match, or output-format flag.

sow show

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

sow show resolves one package reference in the selected Repository and prints the complete Package Object. It is read-only and takes no write lock.

Synopsis

sow show PACKAGE [-C|--workdir DIR] [-r|--repo NAME] [-d|--dist NAME]... [--json]

Flag	Meaning	Default
`-C, --workdir DIR`	Workspace discovery start directory	current directory
`-r, --repo NAME`	Select a Repository	selection rules
`-d, --dist NAME`	Narrow candidates to these Dists; repeatable	Repository scope
`--json`	Wrap the result in the `sow.cli/v1` envelope	false

Package reference

PACKAGE accepts a sha256:<hex> content identity, canonical rpm:<NEVRA> or deb:<name>=<version>:<arch> coordinate, full package filename, or bare binary name. See Package References for the exact grammar.

sow where

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

sow where answers which Dists in the Workspace still carry one Package Object. It is read-only, searches every Repository by default, and takes no write lock.

Synopsis

sow where PACKAGE [-C|--workdir DIR] [-r|--repo NAME] [-d|--dist NAME]... [--json]

Flag	Meaning	Default
`-C, --workdir DIR`	Workspace discovery start directory	current directory
`-r, --repo NAME`	Restrict the search to one Repository	all Repositories
`-d, --dist NAME`	Restrict the search to named Dists; repeatable	all Dists
`--json`	Emit the `sow.cli/v1` envelope	false

Reference resolution

PACKAGE uses the same grammar as sow show: SHA-256 identity, canonical RPM/DEB coordinate, full filename, or bare name.

sow status

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

sow status is the cheap Repository health query. It reads state but does not hash files, verify signatures, recover Operations, build metadata, or take the write lock.

Synopsis

sow status [-C|--workdir DIR] [-r|--repo NAME] [-d|--dist NAME]... [--json]

Flag	Meaning	Default
`-C, --workdir DIR`	Workspace discovery start directory	current directory
`-r, --repo NAME`	Select a Repository	selection rules
`-d, --dist NAME`	Restrict status to these Dists; repeatable	all Dists
`--json`	Emit the `sow.cli/v1` envelope	false

Repository states

Every Repository tracks a Desired Revision in SQLite and the Built Generation represented by its public dists/ tree.

sow build

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

sow build is the explicit Desired-to-Built convergence command. It acquires the Repository write lock, recovers any decidable unfinished Operation, renders and verifies a complete Generation, then switches protocol pointers last.

Synopsis

sow build [-j|--jobs N] [-C|--workdir DIR] [-r|--repo NAME] [-d|--dist NAME]... [-T|--timeout DUR | -N|--no-wait] [--json]

Flag	Meaning	Default
`-j, --jobs N`	Parallel workers; must be at least `1`	logical CPU count
`-C, --workdir DIR`	Workspace discovery start directory	current directory
`-r, --repo NAME`	Select a Repository	selection rules
`-d, --dist NAME`	Build named Dists; repeatable	all affected Dists
`-T, --timeout DUR`	Maximum lock wait; `0` waits indefinitely	`0`
`-N, --no-wait`	Fail immediately when the lock is held	false
`--json`	Wrap the result in the `sow.cli/v1` envelope	false

Without -d, SOW converges every affected Dist in the selected Repository. With -d, only those Dists converge; unselected changes remain dirty.

sow check

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

sow check is the deep read-only gate for a managed Repository. It hashes bytes, validates state, reconstructs expected views, and verifies declared signatures. It never repairs, builds, recovers an Operation, or takes the write lock.

Synopsis

sow check [-j|--jobs N] [-C|--workdir DIR] [-r|--repo NAME] [-d|--dist NAME]... [--json]

Flag	Meaning	Default
`-j, --jobs N`	Parallel verification workers; at least `1`	logical CPU count
`-C, --workdir DIR`	Workspace discovery start directory	current directory
`-r, --repo NAME`	Select a Repository	selection rules
`-d, --dist NAME`	Verify named Dists; repeatable	all Dists
`--json`	Emit the `sow.cli/v1` envelope	false

Verification layers

In steady state, the checker reports nine ordered layers:

sow changes

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

sow changes compares Built Generations. It reports physical Repository-relative file changes; it does not show unbuilt Desired changes and is not a remote transaction protocol.

Synopsis

sow changes [BASE_GENERATION] [-C|--workdir DIR] [-r|--repo NAME] [--json]

Flag	Meaning	Default
`-C, --workdir DIR`	Workspace discovery start directory	current directory
`-r, --repo NAME`	Select a Repository	selection rules
`--json`	Emit the `sow.cli/v1` envelope	false

The command is Repository-wide and rejects -d/--dist.

sow publish

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

sow publish delivers one Repository’s current Built Generation to a named target from the targets: map in sow.yml. The target binds its Repository and provider; the command does not accept --repo or --dist.

Synopsis

sow publish TARGET [--abort | --rebind] [-C|--workdir DIR] [-T|--timeout DUR | -N|--no-wait] [--json]

Flag	Meaning	Default
`--abort`	Abandon a reconciled attempt that has not reached durable commit intent	false
`--rebind`	Confirm and record permitted target name/public endpoint/cache-TTL changes	false
`-C, --workdir DIR`	Workspace discovery start directory	current directory
`-T, --timeout DUR`	Maximum Repository-lock wait; `0` waits indefinitely	`0`
`-N, --no-wait`	Fail immediately when the lock is held	false
`--json`	Emit the `sow.cli/v1` envelope	false

TARGET must name a configured filesystem or r2 publication target. --abort and --rebind are mutually exclusive.

sow retain

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

sow retain manages explicit local Generation roots. retain add can freeze only the current Built Generation; after later builds make it historical, its required package payloads remain protected.

Synopsis

sow retain add GENERATION [-C|--workdir DIR] [-r|--repo NAME] [-T|--timeout DUR | -N|--no-wait] [--json]
sow retain ls             [-C|--workdir DIR] [-r|--repo NAME] [--json]
sow retain rm GENERATION  [-C|--workdir DIR] [-r|--repo NAME] [-T|--timeout DUR | -N|--no-wait] [--json]

GENERATION must be a decimal integer greater than zero.

sow gc

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

sow gc has two deliberately separate modes. With no positional target it collects unreachable local pool payloads. With TARGET it maintains one configured publication target.

Synopsis

sow gc          [-C|--workdir DIR] [-r|--repo NAME] [-T|--timeout DUR | -N|--no-wait] [--json]
sow gc TARGET   [-C|--workdir DIR]                  [-T|--timeout DUR | -N|--no-wait] [--json]

Flag	Meaning	Default
`-C, --workdir DIR`	Workspace discovery start directory	current directory
`-r, --repo NAME`	Select a Repository for local GC only	selection rules
`-T, --timeout DUR`	Maximum Repository-lock wait; `0` waits indefinitely	`0`
`-N, --no-wait`	Fail immediately when the lock is held	false
`--json`	Emit the `sow.cli/v1` envelope	false

gc TARGET -r NAME is a usage error because the target already binds a Repository. --dist is not accepted in either mode.

sow export

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

SOW provides one export subcommand: sow export rpm-leaf. It creates an external, standalone RPM repository whose repodata uses local pool/... hrefs.

Synopsis

sow export rpm-leaf DIST ARCH DIR [--hardlink] [-C|--workdir DIR] [-r|--repo NAME] [--json]

Argument	Requirement
`DIST`	Canonical configured RPM Dist name
`ARCH`	`x86_64` or `aarch64`
`DIR`	Absent or empty destination outside Repository, private-state, and filesystem-target roots

Flag	Meaning	Default
`--hardlink`	Use hard links for trusted, same-filesystem, read-only output	copy files
`-C, --workdir DIR`	Workspace discovery start directory	current directory
`-r, --repo NAME`	Select a Repository	selection rules
`--json`	Emit the `sow.cli/v1` envelope	false

The command accepts no --dist, jobs, timeout, or lock option.

sow log

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

Every write command inside a Repository commits an application-level Operation to that Repository’s SQLite database before it produces any external file side effect. That record is what makes crash recovery possible — and once the Operation reaches a terminal state, the same record is your audit trail. sow log reads it.

Synopsis

sow log [OPERATION] [-C|--workdir DIR] [-r|--repo NAME] [-d|--dist NAME] [--json]
sow log export [FILE] [-C|--workdir DIR] [-r|--repo NAME] [-d|--dist NAME]
sow log prune BEFORE [-C|--workdir DIR] [-r|--repo NAME] [-T|--timeout DUR | -N|--no-wait] [--json]

Operation lifecycle

Understanding the state field is most of understanding the log: