Commands

Every command takes --help. Commands marked reads only never change anything.

Command	What it does
zap	Open the picker for the current repository (--all: every repository)
zap scan [PATH]	List worktrees and their status. Reads only.
zap explain PATH	Show every check behind one worktree's status. Reads only.
zap init [PATH]	Opt a repository in by writing .zap
zap clean [PATH]	Remove merged, empty and missing worktrees of an opted-in repository, after a confirmation
zap history	What zap removed, newest first. Reads only.
zap undo [RUN]	Bring back the branches and worktrees of a run (default: the latest)
zap check	One summary of merged or empty worktrees and free space; exit 3 past a limit. Reads only.
zap map	Draw what coding agents keep on disk. Reads only.
zap schedule on|off|status	Run zap check --notify on a timer
zap roots [add|remove|reset]	Show or change where --all looks
zap version	Print the version
zap completion SHELL	Print a shell completion script (bash, zsh, fish, powershell)

Flags you'll use most

Flag	Works with	Does
-a, --all	zap, scan, clean	Every repository under your scan roots
-n, --dry-run	clean, undo	Show what would happen, change nothing
-y, --yes	clean	Skip the confirmation (needed in scripts)
--fetch	scan, explain, clean	Fetch every remote first, to see merged pull requests
--gh	zap, scan, explain, clean	Also ask GitHub about merged pull requests
--target BRANCH	scan, explain, clean	Measure merges against another branch
--json	scan, explain, clean, check, map, history, undo, roots	Machine-readable output. See JSON output
--no-size	scan	Skip measuring disk use
--unlock-stale	clean	Release locks whose process is no longer running

Other flags

• zap check: --min-stale (default 1GB), --min-free (default 10GB), --notify
• zap map: --list (the default), --tree, --height, --top
• zap schedule on: --every (default 24h, at least 1h)
• zap history: --limit (default 20, 0 for all)

Shell completion

zap completion zsh --help (or bash, fish, powershell) shows how to load completions in your shell.