---
title: "CLI reference"
url: https://loot.build/docs/cli
group: "CLI reference"
status: written
summary: "Every verb loot ships, on one page — the ones worth a sentence described, the rest named."
---

# CLI reference

> Every verb loot ships, on one page — the ones worth a sentence described, the rest named.

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](https://loot.build/docs/cli#cli-rest), 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 <ticket-id>] [--name <n>] [--at <dir>] — Spawn a sealed ephemeral lane over the shared store — the isolation unit for concurrent agents (ADR 0034). --ticket makes the ticket id the lane handle.
- 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 login [<forge>] — Connect this repo to your forge account: type the code it prints into the browser and approve it, then your passphrase locks this repo’s key for a new account, or unlocks your account’s key here. It also adds the forge as a remote, unless origin and forge both name other addresses, when it prints the address instead.
- 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 · runner · runners · seek · shortlog · show · squash · tag · telemetry · ticket · tickets · tutorial · unlock · view`