CLI reference
Every Zit command.
Every command works as zit <command> or git zit <command>; git-zit is installed next to zit for that. For help use git zit -h or git zit help (git turns --help into a manual-page lookup).
All commands take --json. Changes can be named by any unique id prefix, any git revision, or current.
Graph
| Command | Does |
|---|---|
zit init [--from REV] |
Start the graph; REV (default HEAD) becomes current. Idempotent. |
zit status |
Current, every speculative change with its status and reason, every workspace. |
zit show CHANGE |
One change: intent, agent, parents, writes, declared reads, status, evidence. |
zit check CHANGE [--rerun] |
Run the state’s checks that have no evidence. Exit 1 if any fails. |
zit accept CHANGE [--allow-stale] [--rerun] [--linear] |
Make it part of current. Exit 1 if rejected, with the reason. --rerun runs every check again; --linear composes as one commit instead of a merge. |
zit retry CHANGE |
New workspace on current with the change’s edits applied; prints its path. |
zit discard CHANGE… |
Remove speculative changes from the graph. |
Workspaces
| Command | Does |
|---|---|
zit materialise [--from CHANGE] [--intent TEXT] [--agent NAME] [--session ID] |
Create a workspace; prints its path. |
zit claim [--workspace ID] RESOURCE… |
Claim what you intend to write. Exit 1, naming the holder, if other unaccepted work already holds it. |
zit claim [--workspace ID] --edit PATH --content FILE [--dry-run] |
Claim exactly what writing FILE over PATH in the workspace would change, as Zit indexes it: the functions, types, methods, imports or Markdown sections that differ, or the whole file if it is new or unparsed. --dry-run only lists them. For agent tools that guard their own writes. |
zit read [--workspace ID] RESOURCE… |
Declare observed resources: path, path#Symbol, path#. |
zit record [--workspace ID] [--intent TEXT] [--summary TEXT] [--read RESOURCE]… [--dispose] |
Snapshot into a change; prints its id. --summary is what was done and why. |
zit dispose ID… | --all |
Delete workspaces. Recorded changes are unaffected. |
zit clean [--force] |
Delete every local copy Zit made for the repository: workspaces, cached checkouts, verification views, caches. Refuses while a workspace has unrecorded edits or a running agent, or while a clone or verification is in progress, unless --force. The graph is untouched. |
Inside a workspace, record, read and claim need no --workspace. status lists, for each workspace, what it has claimed, what it is writing right now, and overlaps with other unaccepted work.
Agents
| Command | Does |
|---|---|
zit run [--agent NAME] [--intent TEXT] [--session ID] [--from CHANGE] [--keep] [--accept] [--timeout SECONDS] [-- COMMAND…] |
Run a command in a fresh workspace and record its work, its final message and its cost, however it ends. With --agent autohand|claude|codex|pi and no command, a preset. |
zit mcp [--integrator] |
Serve the graph over the Model Context Protocol on stdio. --integrator adds zit_accept and zit_discard. |
zit ui |
Interactive list of changes and workspaces, in the terminal. |
zit web [--port 4747] [--no-open] |
Live graph in the browser. Read-only. |
With --agent autohand, claude, codex or pi and no command, run uses that agent’s headless invocation with --intent as the prompt.
Git
| Command | Does |
|---|---|
zit export [--branch main] [--pr [--base main] [--remote origin]] |
Fast-forward the branch to current. --pr pushes it and opens a pull request into --base with every change’s reason (needs gh); with --pr, --branch must name a branch other than --base, e.g. zit/ready. |
zit sync [--branch main] |
Accept the branch into current, then export. |
The UI
zit ui shows the same data as zit status and refreshes every two seconds.
| Key | Action |
|---|---|
↑ ↓ / j k |
move |
tab |
switch between changes and workspaces |
a |
accept the selected change |
c |
run its checks |
t |
retry it |
d |
discard the change, or dispose the workspace |
r |
refresh |
q |
quit |