Command line
On this page
The plugin puts zest on the PATH of Claude Code's shell only. To type zest in your own terminal, run zest link once from Claude Code (or node "<plugin>/bin/zest" link from a terminal): it puts a zest link in ~/.local/bin, /opt/homebrew/bin or /usr/local/bin, whichever is on your PATH. Until then, every command Zest shows you (in the editor, the browser and the terminal) is written the way your terminal can run it: node "<plugin>/bin/zest" trust … rather than zest trust …. Every command takes a path to an .html file; a folder means its index.html.
Open and stop
| Command | Does |
|---|---|
zest open <file> [--port 4477] [--no-browser] [--root <dir>] | Open the browser on the file in the editor. When the Zest service runs, it serves the page itself, at a private address on its own port, and no server starts. Otherwise (or with --port or --root) it starts a server for the file's folder in the background, or reuses one already serving it. Returns at once. --root serves a wider folder when the page reaches above its own. |
zest demo [folder] | Copy the welcome page into ./zest-demo (or folder) and open it. |
zest serve [--root <dir>] [--port <n>] | Run the server in the foreground, logging to the terminal. Useful when open reports that the server did not start. |
zest stop [<file> | --all] | Stop the server for a file's folder, or all of them. |
zest status | List running servers. |
zest doctor [<file>] [--offline] | What works on this machine, with a fix for anything that does not. Exits non-zero on a 🛑. |
zest link [<folder>] [--force] | Make zest work in any terminal: a link to this Zest in the first of ~/.local/bin, /opt/homebrew/bin and /usr/local/bin that is on your PATH and writable, or in <folder>. It never replaces another program called zest without --force; a link to another copy of Zest it updates. Run it again after a plugin update. On Windows it says which folder to add to your PATH. |
zest link --remove [<folder>] | Take the link back. |
One round of notes (for agents)
| Command | Does |
|---|---|
zest shoot --url http://localhost:<port>/… [--full] [--width 390] | A screenshot of any page on this machine, for a task building in its own copy of an app. |
zest notes pending <file> [--json] | The brief, every open note with its element and line, attached images as paths, hand edits since the last run. |
zest notes start <file> [name] | Start a run (default name rev N). Open tabs say the agent is working. |
zest notes answer <file> <id> --said "…" | Answer a note. The id can be its last few characters. |
zest notes drop <file> <id> --why "…" | Decline a note, saying why. |
zest notes finish <file> [--summary "…"] | Close the run. Open tabs reload and show the answers. |
zest notes log <file> | Every run and answer so far. |
zest notes plan <file> --note <id> [--intent copy] [--specificity exact] [--assumed "…"] [--reference "…"] [--confidence 0.8] --change "…" --files "a, b" --check "…" | A task's reading of one note and its plan, before it edits. --intent is copy, layout, motion, picture, structure, content-model, bug or other; --specificity is exact, directional or open; --assumed and --reference may repeat. Shown in the round's trace; the reading also goes to the ledger. |
zest trace <file> [round] [--open] [--list] [--json] | A round's trace: the plan and what each task did, the models and why, where the time went, checks, the patch, before and after. |
zest label <file> <id> pass|partial|fail [--why "…"] | Mark an answer right, partly right or not right. |
zest eval from <file> [round] [--force] | Turn a round whose answers were labelled right into eval cases. |
zest eval add <file> --base <commit> --mark <commit> --note "…" [--kind compose] [--files a,b] | Set an eval case by hand. --notes <file.json> for several notes; --shot-desktop and --shot-phone for the mark's pictures. |
zest eval run <file> [--case id] [--lanes a,b] [--parallel 3] | Replay cases on your team's lanes, each in its own worktree, and score them against the mark. |
zest eval auto <file> [--lanes a,b] [--dry-run] [--quiet] | One pass of the loop, for a schedule: labelled rounds become cases, each case gets a result on every lane it has none on, and routes move where the evidence says. --quiet prints only when something happened. |
zest gc <file> [--days 30] | Drop round snapshots older than that under refs/zest/rounds/. |
zest eval report <file> / zest eval tune <file> [--apply] | Pass rates and times per kind of work and model; move each kind to the fastest model that holds the bar. |
zest grooves <file> [--json] | What past rounds did on this page: the files each read first and edited, the commands it ran, how long it took. The next round of the same kind reads the latest as a pointer. |
zest notes add <file> "text" | Leave a note from the terminal. |
zest notes repair <file> | Keep a damaged notes file aside (*.damaged-<time>) and start a fresh one. |
zest prompt <file> [--full] | The prompt the editor copies. |
zest shoot <file> [--full] [--width 1440] [--height 900] [--selector <css> | --note <id>] [--out <png>] | Screenshot without the editor, using your Chrome. Saves to .zest/shots/ unless --out. |
When another agent works in the checkout
When Submit hands notes to an agent already working in the page's checkout (how), that agent reads them here. The id is the one your team's extension gave Zest for it.
| Command | Does |
|---|---|
zest inbox <id> [--json] | The hand-offs waiting for that agent and not taken yet: the page, when, and how many of its notes still wait (a note the person took back, or someone answered, is not counted). |
zest inbox <id> --take [--by <name>] [--json] | Take them. Marks each hand-off taken and prints, per page, each note's words, where it is pinned, what the page showed, its pictures, and the zest notes answer line that answers it. |
zest inbox --all [--json] | Every agent with hand-offs waiting, and how many. |
The ledger
| Command | Does |
|---|---|
zest ledger [--since 7d] [--file <f>] [--type request|reading|result|outcome] [--json] | What the ledger holds: rows by type, rounds, how many answers were labelled right, follow-ups, hand edits, restores, merges, and the commonest misses. --file takes a page's path, or the end of its path in the repo. |
zest ledger --rows [same filters] | The matching rows, one JSON object per line. |
zest ledger sweep [repo] | For each answer from this repo not yet settled: is its change on origin/main (merged), or did it land on its branch and then go (reverted)? Uses your refs as they are: git fetch first. |
Before it leaves your laptop
| Command | Does |
|---|---|
zest check <file> [--json] | The checks in Checks and export. |
zest localize <file> | Copy hot-linked images, and images over 20 KB written into the page as data: text, into assets/ and repoint the page. Keeps a version first. |
zest bundle <file> [--out <file>] | One self-contained HTML file. |
Your team's setup, Submit and the button
| Command | Does |
|---|---|
zest trust <file> [--yes] | List what the page's zest.json asks to run (builds, checks, extensions) and approve it. Without --yes it asks. A folder with no index.html (a repo, a worktree) stands for its own zest.json. |
zest trust --list / --revoke <id> | What you approved, or take one back. |
zest options <file> | Everything the page could do that it does not do yet, and the line that turns each on. |
zest runner | Whether Submit is ready on this machine, and if not, why. |
zest runner setup [--yes] [--budget 2] [--turns 100] [--model name] | Give Submit its yes, after reading what a round may do. |
zest runner worker --url <https://...> --key <VAR> --model <id> [--label name] | Run rounds on another model behind an Anthropic-compatible endpoint. --key names the variable that holds the key. zest runner worker off goes back to Claude. |
zest runner off | Take that yes back. |
zest service install | Start the Zest service at login, and mark this browser. It edits pages in place (Editing in place), serves the pages zest open asks for, and answers the Zest Edit button. |
zest service add <repo> / remove <repo> | Which repos the service may open pages from. One add covers every git worktree of the repo, made before or after it; adding a second checkout of a registered repo adds nothing. On Windows Zest cannot see which checkout a dev server runs from, so when several worktrees map one address, the first registered one serves it. |
zest service repos | The registered repos, marked: ✅ there (with how many worktrees it covers), 🟠 covered by another registration of the same repo, 🛑 gone (the folder is not there). |
zest service prune | Take out the registrations marked gone or covered. When a gone worktree was the only one of its repo, it prints the add that keeps the button on that repo's pages. |
zest service status / hello / stop / uninstall | The service's state; mark another browser; stop it; remove the login item. |
Releases
| Command | Does |
|---|---|
zest update [--json] | Is this the newest release? Asks GitHub at most once a day, then says what to run if a newer one is out. |
zest update --now | Ask again now. |
Keys
| Command | Does |
|---|---|
zest keys | Which providers have a key, masked, and where each came from. |
zest keys set <NAME> <value> | Save a key to Zest's config file (mode 600). Names: OPENAI_API_KEY, GEMINI_API_KEY, GOOGLE_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY, PEXELS_API_KEY. An empty value removes it. |
zest help prints all of this; zest version prints the version.