CLI reference
The commands that matter, grouped by what you're doing. Every mutating verb snapshots the working tree first — no manual loot status needed. The tables below are a curated subset; every other verb loot ships is named under Every other verb, and loot <verb> --help prints any verb's own usage block without running it.
Setup
| loot init [--identity <name>] | Initialize a repo here (identity from global config if omitted); refused inside a repo that already exists above you. |
| loot clone <url> <dir> [--identity <name>] [--depth <n>] | Clone a relay or forge repo into <dir>; mints a keypair, pulls changes and any sealed grants, and ends with a materialized working tree. --depth <n> takes only the newest <n> generations of history. |
| loot config list|set|unset|--get <key> [--local|--global] | Read and write config in two scopes — local is .loot/config.local (this repo), global is ~/.config/loot/config (this machine). |
Local
| loot status [--porcelain|--json] [--] [<path>...] | Show the working change, read-only — no snapshot, no ceremony. Naming paths limits the listing to them. |
| loot diff [<from>] [<to>] [--content|--stat] [--] [<path>...] | Show which paths changed. --content adds a unified diff of each path it already calls readable; --stat adds insertion/deletion counts. A sealed, embargoed or burned path reports why rather than a misleading zero. |
| loot diff [--porcelain|--json] | One frozen machine shape whatever else you typed — a row per changed path with its class, address, tier, the rung of the content ladder it stopped on and its counts, then a closing disclosure tally. An unreadable row carries the rung and a dash for the count. |
| loot describe -m <message> | Record the working tree and name the change. Your first verb on new edits. |
| loot new [-m <message>] | Finalize (sign) the working change and start a fresh one on top. |
| loot edit <change-id> | Reopen a finalized change to amend it; supersedes it on finalize (ADR 0032). |
| loot log | Show change history with visibility hints; a divergent change is marked !. |
| loot heads [--porcelain|--json] | List every live head of this position — version id, subject, author, when, landed or not, and the operation that introduced it. @ marks the one the working view sits on. Read-only. |
| loot cat <path> [<selector>] | Write a path's recorded content, at the current change or the one <selector> names, to stdout verbatim — binary included. A path you cannot open is a refusal naming which it is (missing, sealed, embargoed, burned), never empty output. |
| loot surface [--force] | Materialize what the current identity may see; sealed paths are skipped. It writes the working tree, so it refuses over edits no change records unless --force. |
| loot restore [--source <selector>] <path>... [-p] [--dry-run] | Discard the uncaptured edits to the named paths, returning each to its content in the working change — the per-path form of what surface does to the whole tree. -p asks per hunk; unnamed paths are left alone. |
| loot split [-p] -m <subject> [<path>...] | Move the named paths out of the working change into a new finalized change below it; the remainder stays on top. -p asks per hunk instead, and there the paths narrow what you are asked about rather than naming what moves. |
| loot move <selector> --onto|--before <selector> [--branch] | Re-anchor one change on a different parent, or reorder it below its own parent. Not a rebase: nothing is deleted — it is recorded afresh as a superseding version keeping its durable id, and its live descendants travel with it. |
| loot notes add|append|show|remove [<selector>] [-m <text>] | Attach, extend, read or withdraw freeform text on a recorded change without amending it — the version id does not move, because a note is a signed attestation. ⚠ Plaintext on the attestation lane. |
| loot range-diff <left> <right> [--stat] | Compare two series after a rework: what the sides have in common, what sits on one side only, and what moved inside each common change. Pairing is by the durable change id, so a copy under a fresh handle cannot pair. |
| loot gc [--dry-run] [--pack] | Prune loose objects no change references. --pack also consolidates them into per-address-bucket packs, and reports the count-objects census before and after. |
| loot verify [--accept-loss] [--unreachable] | Integrity-check the object store: rehash every object, name missing ones by referencing change. Exits 1 on problems; --accept-loss records unrecoverable losses so only new damage fails. --unreachable adds the other direction — objects present and referenced by nothing, listed with their size and counted apart by storage form. It deletes nothing and cannot change the exit status: unreachable is garbage, not damage. |
| loot undo · loot op log · loot op restore <n> | Step the view back / list / jump the operation log (redo included). |
| loot abandon <selector> [--head] | Drop one version of a divergent change, or a whole fork tip; undoable. |
| loot adopt [<version-id>] [--discard-wip] | Catch this working tree up to landed history. |
Lanes (concurrency)
| loot lane new [--ticket <n>] [--name <n>] [--at <dir>] | Spawn a sealed ephemeral lane over the shared store — the isolation unit for concurrent agents (ADR 0034). --ticket derives the handle t<n>. |
| loot lanes [--porcelain|--json] | List lanes with path, tip, in-flight PR, dirty/clean, heartbeat and owner; * marks this session’s. Check before acting on shared state. |
| loot lane take <id-or-name> <path>... | Copy the named uncaptured primary paths into a lane — a copy, never a move. |
| loot lane name <n> | Inside a lane: promote it to a dock, which persists until removed. |
| loot lane rm <id-or-name> · loot lane gc [--stale-hours <h>] | Reap one lane, directory and registry entry (not undoable) / sweep unnamed lanes that landed or went stale. |
Sync
| loot bundle <file> · loot apply <file> | Offline sync: write a sync bundle (ciphertext, no private keys) / merge a peer’s. |
| loot remote add|remove|list | Register named relay URLs (origin is the conventional default). |
| loot push [<url>] · loot pull [<url>] | Publish changes to a relay / fetch, merge, and converge from one. |
| loot serve [--dir <path>] [--addr <host:port>] [--allow <pubkey>]... | Run a relay: stores and forwards sealed content, and never holds a restricted key. Each --allow admits one key to push to it and read from it; with none, any valid signature may push and anyone who can reach it can read, Internal content included. |
| loot conflicts · loot resolve <path> <file> | List paths needing human resolution / resolve one from a file. |
Grants & visibility
| loot grant <path> <identity> <file> | Write a targeted grant bundle for file delivery. |
| loot grant --relay <name> <path> <identity> [--expires <ts>] | Seal and deliver a content key via the relay’s mailbox; --expires makes the recipient reject the grant once now is past ts. |
| loot grants [<url>] · loot pull-grants [<url>] | Peek the pending grant count / fetch, verify, and apply sealed grants. |
| loot maroon [--hard] <path> <identity> | Cut an identity off future access; --hard also signs a request that peers drop the old key. |
| loot migrate <path> <vis-spec> | Change a path’s visibility: internal | restricted=a,b | embargoed=<ts>. |
| loot manifest | Show the grant audit trail (grantor/grantee pubkeys, timestamps) and the attestation lane — landmarks, notes and sign-offs — each of which is reported whether or not the other holds anything. |
Identity
| loot keygen · loot whoami | Generate an identity keypair / show this repo’s public key. |
| loot id export <file> · loot id import <file> | Move the same identity between machines (passphrase-encrypted). |
| loot peer add|remove|list | Manage the local nickname → public key registry (loot’s known_hosts). |
Every other verb
The rest of the surface, named rather than described — a check pins this list plus the tables above to the CLI's own declared verb set, so together they are every verb loot ships and nothing it does not. Run loot <verb> --help for any of them.
absorb · apply-patch · archive · attest · bisect · blame · buoy · burn · cherry-pick · clean · completions · converge · count-objects · doctor · duplicate · embargo-status · evolog · explain · ferry · fetch · format-patch · gates · grant-status · grep · lock · merge · pipeline · propose · purges · rehome · relay · revert · runners · seek · shortlog · show · squash · tag · telemetry · tutorial · unlock · view