Reference

CLI reference

Every bay command, its purpose, and the result it prints.

bay is in development. These pages describe bay as it will ship.

Daily commands

Five commands make the daily loop: start, land, status, watch and undo. bay talk and bay status --fleet help agents on different machines work together.

Command	Purpose
`bay start <intent> --paths <path>…`	Open a change: a fresh trunk, a sparse view of the declared paths, and the change record.
`bay start <intent> --intent-revision <rev>`	Name the revision of the external reference (default `1`).
`bay start --resume <change>`	Restore a change: checkpoint its draft and bring in newer trunk.
`bay start <intent> --new`	Open a follow-up change after the change of that intent landed.
`bay land [--change <change>]`	Freeze the draft, build the candidate, check it, and land it. Returns at once.
`bay land --wait [--observe <seconds>]`	Run the landing here and return its outcome. `--observe` stops watching; the run goes on.
`bay land --abandon`	Give up the change. Another actor can then adopt its intent.
`bay status [<change>]`	Current state, read from trunk and refs.
`bay status --fleet`	Every machine, actor and open talk that the local cache knows.
`bay watch [--since <cursor>]`	Landings and events after the cursor that touch the inputs of your change.
`bay undo <change>`	A new change that reverses one landing. History before it stays.
`bay talk <actor> <text>`	Send one short message to one actor through the shared remote.

Setup commands

A person or a setup script runs these commands. An agent does not run them in the daily loop.

Command	Purpose
`bay install`	Place bay at `~/.local/bin/bay`, add its hook entries, and copy the bay skill.
`bay doctor`	Check this machine: Git and Claude Code floors, the remote, hook entries, and the skill.
`bay host init <path> [--trunk <name>] [--object-format sha1\|sha256]`	Create a bare repository on reftable whose trunk is append-only.
`bay share <change> [--remote <name>] [--bundle <file>]`	Push a change and its evidence to a remote, or write them to a bundle.
`bay executor run [--once] [--interval-s <n>]`	Drive queued operations to an outcome on this machine.
`bay hook <event>`	The agent hook entry point. The agent product calls it, not the agent.
`bay update [--channel stable\|latest] [--version <x>]`	Install a newer bay release.

Global options

Option	Effect
`-C <path>`	Run as if bay started in `<path>`, like `git -C`.
`--json`	Print only the `bay.result/1` document, with no human text on stderr.
`--version`	Print the bay version.

Every command that reports state prints one bay.result/1 JSON document on stdout. Human text, if any, goes to stderr. No command asks an interactive question. Unknown is never success, so an unknown check never exits 0.

Exit	Meaning
`0`	ok, landed, or accepted and queued. `"published": false` says what has not happened yet.
`10`	blocked: a policy or state refusal, with `allowed` and `retry_when`.
`20`	failed: an operation fault, with a receipt.
`2`	usage error.

CLI reference

Every bay command, its purpose, and the result it prints.

bay is in development. These pages describe bay as it will ship.

Daily commands

Five commands make the daily loop: start, land, status, watch and undo. bay talk and bay status --fleet help agents on different machines work together.

Command	Purpose
`bay start <intent> --paths <path>…`	Open a change: a fresh trunk, a sparse view of the declared paths, and the change record.
`bay start <intent> --intent-revision <rev>`	Name the revision of the external reference (default `1`).
`bay start --resume <change>`	Restore a change: checkpoint its draft and bring in newer trunk.
`bay start <intent> --new`	Open a follow-up change after the change of that intent landed.
`bay land [--change <change>]`	Freeze the draft, build the candidate, check it, and land it. Returns at once.
`bay land --wait [--observe <seconds>]`	Run the landing here and return its outcome. `--observe` stops watching; the run goes on.
`bay land --abandon`	Give up the change. Another actor can then adopt its intent.
`bay status [<change>]`	Current state, read from trunk and refs.
`bay status --fleet`	Every machine, actor and open talk that the local cache knows.
`bay watch [--since <cursor>]`	Landings and events after the cursor that touch the inputs of your change.
`bay undo <change>`	A new change that reverses one landing. History before it stays.
`bay talk <actor> <text>`	Send one short message to one actor through the shared remote.

Setup commands

A person or a setup script runs these commands. An agent does not run them in the daily loop.

Command	Purpose
`bay install`	Place bay at `~/.local/bin/bay`, add its hook entries, and copy the bay skill.
`bay doctor`	Check this machine: Git and Claude Code floors, the remote, hook entries, and the skill.
`bay host init <path> [--trunk <name>] [--object-format sha1\|sha256]`	Create a bare repository on reftable whose trunk is append-only.
`bay share <change> [--remote <name>] [--bundle <file>]`	Push a change and its evidence to a remote, or write them to a bundle.
`bay executor run [--once] [--interval-s <n>]`	Drive queued operations to an outcome on this machine.
`bay hook <event>`	The agent hook entry point. The agent product calls it, not the agent.
`bay update [--channel stable\|latest] [--version <x>]`	Install a newer bay release.

Global options

Option	Effect
`-C <path>`	Run as if bay started in `<path>`, like `git -C`.
`--json`	Print only the `bay.result/1` document, with no human text on stderr.
`--version`	Print the bay version.

The result

Exit	Meaning
`0`	ok, landed, or accepted and queued. `"published": false` says what has not happened yet.
`10`	blocked: a policy or state refusal, with `allowed` and `retry_when`.
`20`	failed: an operation fault, with a receipt.
`2`	usage error.