Skip to content
Zit
Esc
↑↓navigate↵open⌘Jpreview
On this page

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. A name that matches nothing is zit: unknown revision: <name>; a prefix that matches more than one object is zit: ambiguous revision: <name> names more than one object; give more characters. Both exit 2.

Under --json, a failure is a JSON document on stdout, {"error": "<message>"}, with the same message on stderr and exit code 2:

$ zit show --json nope
{"error":"unknown revision: nope"}
zit: unknown revision: nope

The reports of status, show, log, diff and doctor carry "schema": 1 at the top level. The number changes when a field changes meaning or goes away; added fields keep it. The reports of record, accept, check and run have no schema field.

Graph

Command Does
zit init [--from REV] Start the graph; REV (default HEAD) becomes current. Idempotent. On a repository with no commits: HEAD has no commits yet: commit first, or run `zit init --from <rev>` .
zit status Current, recorded changes, Zit workspaces and registered Git worktrees, with tasks, diff sizes and merge/cleanup assessments.
zit show CHANGE [--log] One change: intent, agent, parents, writes (and renamed old -> new lines), declared reads, status, evidence. --log prints the agent output kept by zit run --log instead; with none, zit: no log recorded for <id>: run the agent with zit run –log``, exit 2.
zit diff CHANGE [--stat] [--against CHANGE] What a change did: its diff against its base, as git diff prints it. --against compares with current, an id or any git revision instead of the base; --stat prints only the summary of changed files. JSON: {schema, change, against, diff}.
zit log [-n N] Accepted history from current backwards: who, what, why, and what it cost. -n, --max-count limits it (default all).
zit check CHANGE [--rerun] [--only NAME]… Run the state’s checks that have no evidence. Exit 1 if any fails. --only runs just the named checks (repeatable); a name no check has is zit: no check named nope; declared: ui, api, exit 2.
zit accept [CHANGES]… [--batch] [--dry-run] [--allow-stale] [--rerun] [--linear] Make a change part of current, or several as one batch (below). 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. All or nothing: every name is resolved before anything is removed. A change that is not speculative (current, an accepted change, a plain commit) is zit: not a speculative change: <id>, exit 2. JSON: {"discarded": [ids]}.

zit log

$ zit log -n 2
0562dfa1f2   1s  claude      Add a note to README.md
                 Added a note to README.md and nothing else.
                 34012 in, 1840 out, $0.1865
a46dcab1f4   2s  r           readme note
2 changes, 34012 tokens in, 1840 out, $0.1865

Per change: id, age, agent, the first line of the intent; then the first line of the account and the usage when the agent reported them. The last line sums the listed changes; the dollar figure appears only when at least one change reported a cost. JSON: {schema, changes: [change…], totals: {changes, input_tokens, output_tokens, cost_usd}}, cost_usd null when nothing reported one. The text form prints an age, not a timestamp; the JSON has time.

Accepting several changes

zit accept A B C      # these three, composed in order, checked once, landed together
zit accept --batch    # every change whose status is verified, in status order

The changes are composed onto current one after another. The checks run once, on the combined state. Current moves once, by compare-and-swap; if it moved meanwhile the whole batch is retried. Each change keeps its own commit and reason in history (a compose commit, or with --linear one commit carrying Zit-Change).

A change that cannot join is skipped and reported, with its reason: already accepted, stale (including against an earlier member of the batch, which by names), text conflict, parse failure. The rest still land:

$ zit accept caaf76d83e 0ac25d008f
landed   0ac25d008f  readme note 2
skipped  caaf76d83e  invalid: stale
    shop.py#price written here and by e4d5ff04cd
current is 0ac25d008f (1 landed, 1 skipped; checks: 0 run, 1 reused)

--batch picks the changes whose status is already verified: a change that is stale, conflicting, failed or still without evidence is not in the batch and is not listed as skipped. Run zit check on changes first, or name them.

When a check fails on the combined state, nothing lands, and Zit cannot say which change is responsible:

$ zit accept 723d3c69cb 828ccb6228
rejected: failed checks: t on the combined state of 723d3c69cb, 828ccb6228; nothing landed
next: accept one at a time to find the change responsible: `zit accept <change>`

Exit 1. JSON: {"outcome": "accepted", "current", "landed": [ids], "skipped": [{change, reason, detail}], "verdicts"} or {"outcome": "rejected", "failed": [checks], "tried": [ids], "skipped": […]}. --allow-stale, --rerun and --linear apply to the batch; --batch and --dry-run cannot be combined.

zit accept --dry-run

Composes and validates one change without landing it or running anything: staleness, the text merge, the parse check, then which checks (current’s and the change’s) would run and which have evidence to reuse.

$ zit accept --dry-run 7318b6ae71
would accept 7318b6ae717d5ff675b63a8460cefa67dedb7221 (fast-forward); checks: t (run)

composed onto current instead of fast-forward when current has moved; already accepted; or rejected: … with exit 1, as accept would print. JSON: {"outcome": "would-accept", "composed": bool, "checks": [{check, run}]}, {"outcome": "already-accepted"} or the rejection. --rerun marks every check as run; --allow-stale applies. [[derive]] commands are not run, so a check whose input is a generated file may show run where a real accept would reuse evidence.

Rejections

rejected: stale, rejected: conflict (text does not merge) and rejected: failed checks: … are described on Concepts and zit.toml. One more: rejected: does not parse after composing: <paths> when the merged text of a file has syntax errors that neither side had (zit.toml).

Workspaces

Command Does
zit materialise [--from CHANGE] [--intent TEXT] [--agent NAME] [--session ID] Create a workspace; prints its path. Refuses when the volume holding Zit’s home has less than zit.minFreeMB free (zit.toml).
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 | --orphaned [--force] Delete workspaces. Recorded changes are unaffected. Needs ids or --all; with neither it is a usage error (exit 2). --orphaned deletes every workspace whose zit run is gone and that has no unrecorded edits; --force also those with edits. Workspaces without an owner (made by hand or over MCP) are never touched by --orphaned.
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.

Tasks, diffs and safety in status

zit status shows the task and agent, N files +added -removed (with a separate binary-file count), and independent merge and cleanup assessments. The target is current (refs/zit/current), whose commit is printed in the report. Managed workspace diffs compare with their last recorded base; ordinary Git worktree diffs compare with the merge base of HEAD and current. Renames count as a deletion and addition. Non-ignored untracked files, including empty files, are included.

ready means the snapshot passes the preview; blocked names a condition to fix; review requires checks or evidence of agent inactivity; not-needed means the work is already included; unknown means inspection failed. These are observations, not automatic merge or deletion actions. zit accept always revalidates. Status does not execute checks, clean filters, hooks, fsmonitor or custom merge drivers. Filter-dependent files are inspected as raw bytes, so their physical diff can differ from the normalized Git diff. Ignored files are excluded from diff sizes.

A managed workspace with unrecorded edits or a live owner is blocked. A clean workspace whose recorded owner has finished can be disposed of while its recorded change still awaits acceptance: the change remains in the graph. cleanup: ready applies to this workspace only; zit clean also protects every other workspace and active verification/clone. Checks of a change’s own state do not establish readiness of its composition: status names any checks still required there. Scan errors produce a null diff and unknown readiness, never a clean bill of health. Every request scans mutable workspace contents freshly, rather than relying on the awareness cache. Clean manual or MCP workspaces have no recorded owner and therefore require an activity review before disposal.

Ordinary Git worktrees appear separately, including locked, detached, bare, primary and missing entries. Git cannot identify an agent reliably from a branch name or commit author. Set explicit local metadata on an agent branch:

git config branch.agent-pricing.zit-task "Fix discount rounding"
git config branch.agent-pricing.zit-agent codex

Task fallback is the standard branch.<name>.description, then the latest commit subject; task_source labels the origin so an inferred subject is distinguishable from an assigned task. Missing agent metadata is shown as unknown. A Zit-Agent commit trailer is also recognized. Metadata does not modify commits or refs.

Ordinary worktrees whose HEAD is not retained by ancestry in current cannot be recommended for cleanup, even if commits are patch-equivalent. Primary checkouts, locks, Git operations in progress and uncommitted edits block cleanup. A clean, retained ordinary worktree requires review of ignored files and agent activity; Git cannot prove that no process is using it. A clean text merge still requires Zit recording/verification before integration. Status never removes ordinary Git worktrees, including through the TUI’s dispose key.

JSON and MCP preserve the existing fields and schema 1, adding diff and merge to changes; diff, merge, cleanup and inspection_error to workspaces; and a git_worktrees array. An assessment is {state, reasons}. Non-UTF8 ordinary paths have a readable path plus lossless path_bytes. The TUI and web ledger show the same task, size and assessment data. Fresh snapshots require more I/O than the older change-only status benchmarks.

Paths given to claim and read are named the way git names files, relative to the workspace root, however they are spelt: ./Cargo.toml, docs/../Cargo.toml and the absolute path are one claim, Cargo.toml. A path that leaves the workspace (../x, /etc/hosts) is zit: ../x is not a path inside the workspace; . or an empty string is zit: . names no file. Both exit 2.

zit dispose --orphaned prints disposed <id> (<agent>), kept <id> (<agent>): unrecorded edits; record it or pass --force, or no orphaned workspaces. JSON: {disposed, kept}.

Agents

Command Does
zit run [--agent NAME] [--intent TEXT] [--session ID] [--from CHANGE] [--keep] [--accept] [--timeout SECONDS] [--log] [-- 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. --log keeps the last 64 KB of the agent’s output (stdout and stderr) with the change; zit show --log prints it.
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 machine

Command Does
zit doctor Check this machine and repository: git, Zit’s home, copy-on-write, free space, the graph, zit.toml’s programs, agents on PATH. Exit 1 if anything fails. Runs before the git-version gate and outside a repository.
zit completions bash|zsh|fish Print a shell completion script: zit completions zsh > ~/.zfunc/_zit. Needs no repository. Completes zit, not git zit.

zit doctor prints one line per probe, <pass|warn|fail> <name> <detail>:

$ zit doctor
pass  git             git version 2.48.1
pass  home            ~/.zit/shop-0cdd0290da587241 (writable)
pass  copy-on-write   apfs: workspaces are clones
pass  free space      5.1 GB free on the volume holding ~/.zit/shop-0cdd0290da587241
fail  repository      zit is not initialised in this repository; run `zit init`
pass  agent autohand  0.9.9-alpha.ae34d3f (ae34d3f)
pass  agent claude    2.1.290 (Claude Code)
pass  agent codex     codex-cli 0.159.2
pass  agent pi        0.84.4
pass  gh              gh version 2.65.0 (2025-01-06)
pass  languages       c#, go, java, javascript, python, ruby, rust, typescript
Probe Fails when Warns when
git missing, or older than 2.38
home Zit’s home is not writable
copy-on-write the file system has no clonefile/FICLONE: workspaces are plain checkouts
free space under 1 GB free on the volume holding Zit’s home
repository not a git repository, not initialised, or refs/zit/current missing
zit.toml it does not parse, or a run, derive or prepare program is not on PATH: `prog` (check t) is not on PATH
agent autohand, claude, codex, pi not on PATH; otherwise the first line of --version (5 s timeout)
gh not on PATH (honours ZIT_GH)
languages a built-in grammar fails to load

A program is looked up by its first word; a program given with a / in it is accepted without being checked. JSON: {schema, checks: [{name, status, detail}]}.

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, Ctrl-C quit

Was this page helpful?