grid is the daemon's own front door: it starts and stops gridd, files and moves cards, and approves plans from a terminal. Every write goes through the running daemon, so a card filed from a script appears on the board at once and passes the same gates.
Bare grid is grid status, and grid --help prints the table the sections below are drawn from. grid help prints the same table followed by the guidance topics. Flags are long form only: --stage review, never -s. A bare -- ends the flags.
Reads such as card ls and card show work from the files on disk when the daemon is down, and say so. Writes do not: card new, card move, card attention add, plan approve, review, worktree gc and every plugin verb refuse with exit 1 and the fix grid start. Writing round the daemon would skip the transition hooks and be overwritten on its next flush.
A <ref> is a card slug, its file path, or the number at the front of its title. A ref that matches more than one card is refused with the candidates listed.
| COMMAND | DOES |
|---|---|
grid start |
Starts gridd detached, waits for /_health on 127.0.0.1:6724 and prints the URL, or the log tail if the boot fails. |
grid stop [--force] |
Asks the daemon to shut itself down over its own loopback route first: POST /api/shutdown, authenticated with the token it wrote to <GRID_HOME>/active-token at boot. Then SIGTERM if that route did not answer, ten seconds, then SIGKILL. Says which one worked. On Windows the route is the only polite step there is: Node maps SIGTERM to a hard TerminateProcess there, so a daemon that ignores the route waits out the ten seconds and is killed. Refused from a linked git worktree with the real home, because the only daemon in reach there is the one serving your sessions: run it from the main checkout, set GRID_HOME to the scratch home you mean, or pass --force. |
grid restart [--force] |
Stop, then start. Refused wherever grid stop is, before anything is stopped. |
grid status |
Whether it runs, the pid, the URL, the workspace and the state directory. Works without the daemon. |
grid logs |
Tails the daemon log. Streams, so it has no --json. |
grid open |
Opens the board URL with the system opener. |
grid doctor |
Checks claude, git, make and lsof. On Windows it checks just claude and git, since Grid uses netstat instead of lsof there and runs projects without make. Notes tmux as optional on macOS and Linux, and does not offer that row at all on Windows, where the tmux runtime cannot run. Lists every gridd on the machine, flagging the abandoned ones. Exit 1 if a required tool is missing. |
grid demo [--force] [--workspace <dir>] |
Writes the demo project and a populated board into the workspace. Through the daemon when it runs, straight to disk otherwise. A demo that already exists is exit 5 until you pass --force. |
| COMMAND | DOES |
|---|---|
grid card new "<title>" |
Files a card into Inbox through the same capture route as ⌘N. Flags: --project <name>, --stage <stage>, --type <type>, --parent <ref>, --difficulty <rung>, --blocked-by <ref,ref>, --new-project. Without --project the project is guessed from the text; an unknown one is exit 3 unless you pass --new-project. Titles are capped at 60 characters, exit 2 beyond that. |
grid card ls [--stage <stage>] [--project <name>] |
Slug, stage, project, title, and for a blocked card what it is waiting on: starts when <ref> closes (it does, by itself, the moment the last one does) or, for a subcard, the plainer blocked by <ref> (a subcard has no session of its own; its masterplan does that work by hand). Reads the files directly when the daemon is down, without live session state. |
grid card show <ref> |
The card, its body and its review notes. Header only when the daemon is down. |
grid card move <ref> <stage> |
The stage move. Stages are inbox, prepare, doing, review, deliver, verify and close. A move to deliver on a project with Deliver switched off is exit 4. A card with a live session is told about the move. |
grid card land <ref> |
Merges the card's branch into its base, the same merge Close performs, including for a card that closed with its branch stranded. |
grid card attention add <severity> "<headline>" --detail "<text>" [<ref>] |
Records something the user must inspect, decide or accept. Grid writes it under ### Needs your eyes in the card's last ## Review block, adding the block if there is none, as a severity-tagged headline followed by the detail, worst first and in place of a lone none. Severity is critical, important or minor; the headline is one plain sentence of at most 100 characters, exit 2 otherwise. The same severity and headline again replaces the earlier item. The ref defaults to the card whose session runs the command. An item belongs to one handover: under the Command rule Grid draws it into the last block again when the card enters Review, and it is cleared when the card is sent back to Doing. |
grid plan approve <ref> |
Answers the Approve option of the question the card is waiting on, stored or open in the live pane. When nothing is asking and the card is in Prepare, it moves the card to Doing. A question with no Approve option is exit 5. A sandbox that denies the daemon connection returns exit 1 with its own fix and leaves the stage unchanged. |
grid plan save <json-file> [--revision <n>] [--reason <text>] [--card <ref>] |
Saves an execution plan revision through the same route and checks as grid execution save, at the card's current revision unless --revision names one. A revision after the first needs --reason. Under the Validated plan format a refused plan is exit 4 with every problem in one message, each named by its field, such as nodes[3].weight, and each fix on the fix: line; --json lists them in error.detail.problems. A saved plan prints plan saved · 2 nodes · rev 1 · ready: build, then one advice: line for each contract rule the plan should still follow. Under the Free plan format the plan is checked as grid execution save always has. The card defaults to the one whose session runs the command. |
Model and effort are not flags. They come from the workspace matrix and the card's difficulty rung, and you change them in the app.
A card's own session uses these to read and settle its saved plan. Inside a session the card comes from GRID_CARD_PATH; from anywhere else pass --card <ref>.
| COMMAND | DOES |
|---|---|
grid execution status [--json] [--full] |
A summary of at most 2 KB: stage, route, ready nodes, what each waiting node waits on, open nodes with the evidence of the failed ones, and the passed ones by ID. --json gives the current plan and every result, without the revision history, the diff baseline and the settled-result history; --full adds those three back. |
grid execution start <node-id> |
Claims an agent task or manual check. Prints one line, such as t-x claimed · rev 3 · ready: t-y. A start that is not ready or has no capacity is exit 4, with a fix that names where to read what it waits on. |
grid execution report <node-id> passed|failed|skipped <evidence> |
Settles a claimed node with its evidence. One line. |
grid execution retry <node-id> --reason <diagnosis> |
Puts a node back to pending, with the diagnosis that justifies another run. One line. A retry with no reason, or with the reason of the node's last retry, is exit 4. |
grid execution save <json-file> --revision <n> [--reason <text>] |
Saves a plan revision, checked as grid plan save describes. The newest five revisions keep their whole plan; older ones keep their number, reason and time. One line, and any advice: lines. |
grid execution brief <text-file> |
Saves the handoff brief, at most 12,000 characters. One line. |
grid execution finish --note <file> |
Hands a card in Doing to the next stage on its route. The note holds the Review prose: Needs your eyes, Assumptions, What changed, How to test. Grid adds Files touched, one bullet per changed file by absolute path, and Branch, both read from git; writes the ## Review block into the card in place of its last one; and moves the card through the same gates as grid card move. Prints one line, such as northwind-41 moved to review · 3 files touched · branch grid/northwind-41. A refused move is exit 4 with the gate's own reason and fix, and the block stays written for the retry. A missing or empty note is exit 2. With the Finish gate rule off it is exit 4, and the fix says to write the sections and use grid card move. |
grid wait --checks|--subcards [--since <cursor>] [--timeout <s>] |
Blocks until a check settles or is reset (--checks), or one of a masterplan's subcards changes stage or session status (--subcards), then prints what changed, the ready nodes and the next cursor. A check starting is not a change. Without --since it waits for a change from now; with a cursor that no longer matches it answers at once. --timeout defaults to 100 seconds, under Claude Code's two-minute shell limit, and stops at 540. Exit 0 on a change, 7 when the timeout passes first, with the cursor in data and in the fix. |
Every grid execution command takes --full to print the daemon's whole answer instead.
An independent reviewer records its findings and verdict with these instead of writing the ### Adversarial review section by hand. Grid writes the section on the card from what was recorded, in the same format, and the reviewer's turn ending settles the round as a hand-written verdict does. Both take a <ref> that defaults to the card whose session runs the command.
| COMMAND | DOES |
|---|---|
grid review finding <severity> "<headline>" --evidence "<text>" [--file <path> [--line <n>]] [<ref>] |
Records one finding in the card's current review round, written as - [critical] The headline (path:line). The evidence. Severity and headline follow the attention-item rules, exit 2 otherwise. The same severity and headline again replaces the earlier finding. Until the user decides the round, a finding recorded after the reviewer's turn ended amends it. Exit 4 when the card is not in Review, has no independent round, or the round is decided. |
grid review verdict clean|findings [<ref>] |
Records the round's verdict. clean over a recorded finding is exit 4; a finding recorded after clean turns the verdict to findings. |
The Review commands and Attention items rows in Settings > Workspace settings decide which Grid reads when a card carries both: what was recorded, with any hand-written bullets beside it, or only what the card's text says. A card written by hand reads the same either way.
| COMMAND | DOES |
|---|---|
grid projects ls |
The board's projects, and the folders that hold more than one. |
grid projects fold <folder> [--dry-run] [--force] [--strand-branches] |
Folds the projects one folder split into one. --dry-run prints what would move; --force overrides a live session; only --strand-branches waives a card's worktree branch. |
grid projects unfold <id> [--strand-branches] |
Reverses a fold by its id. |
grid worktree ls |
Every per-card worktree with its card, repo, branch, stage and size, and which are orphaned. |
grid worktree gc [--force] |
Removes orphaned worktrees. Keeps one with uncommitted work unless you pass --force. |
grid worktree rm <card> [--force] |
Removes one card's worktree, same guard. |
grid hooks install |
Re-registers Grid's Claude Code hooks in the workspace and every project checkout, through the running daemon, and prints the files and the command they run. The daemon does this itself at boot; this is for a machine whose settings still name a hook script that no longer exists. |
grid memory write <tab> "<heading>" [--body "…"] [--project <name>] |
Adds a line to a project's memory. Tabs are facts, decisions, runbook and environment. The project defaults to shared. |
grid memory ls [--tab <tab>] [--project <name>] |
What a project remembers, numbered per tab. |
grid project delivery <name> branch|pr|local|push |
Records how a project's work lands: branch commits on the card branch and pushes that branch, merging nothing and opening nothing, pr pushes the branch and opens a GitHub pull request, local commits on the card branch and Grid merges it into the base ref in your checkout with nothing reaching origin, push is that same merge followed by a push of the base branch. Allowed at any time, mid-card included; live sessions on the project are told. The same setting as HOW WORK LANDS in the project's Settings; the first card to reach Deliver on a project that has not chosen asks you, then runs this. |
grid project permissions <name> trusted|standard |
Sets whether a project's Claude agents run shell and web calls without the auto-mode classifier. trusted skips it; every denied row and the deploy question in the Queue still apply. standard is the default: the classifier decides, and a refusal is asked in the Queue. |
| COMMAND | DOES |
|---|---|
grid plugin ls [--trust] |
The loaded roster. --trust adds the trust word, the signer and whether the signature still holds. |
grid plugin install <path> |
A directory is recorded pinned; a .gridplugin file is verified and installed. grid plugin add is the same verb. |
grid plugin dev <dir> |
Records a directory unpinned, for one you are editing. |
grid plugin pack <dir> [--key <pem>] [--out <file>] |
Builds the .gridplugin artefact, signed when you pass a key. |
grid plugin keygen |
Prints a fresh Ed25519 keypair. It is not written anywhere. |
grid plugin trust [<fingerprint>] [--revoke <fingerprint>] |
Lists the publisher keys this workspace believes, believes one, or stops. |
See plugins for what a signature and a trust state mean.
| COMMAND | DOES |
|---|---|
grid usage |
The plan meters, as Claude Code's own usage screen shows them. |
grid usage --by <key> [--days <n>] |
The cost table, keyed by model, project, session or account, over the last thirty days by default. |
grid usage --report cards [--days <n>] [--project <p>] |
Where top-level cards' lead time went: hours and share per time sink, then one line each for polling share, subagent mix, review and deliver bounces, heavy-check queue wait, sessions ended by a daemon restart, and Copilot tokens. --json prints the route body unchanged. It cannot be combined with --by. |
grid update [--channel <name>] |
Asks the feed whether a newer build exists on the channel, alpha unless GRID_UPDATE_CHANNEL says otherwise, and counts the sessions that would stop. It only checks: the daemon ships inside the app, so the install happens from the app's update chip. |
grid version |
The version, and whether this is a packaged build. |
grid help <topic> [page] prints the guidance a card's agent works under, rendered from the same text its stage prompts carry, so it answers without the daemon. The testing, permissions, authorization and handoffs topics show the workspace's own wording when that section was edited on the Agents page. A page is at most 3,000 characters; a longer topic ends each page with the command for the next one, such as grid help plan-format 2. With --json the data is {topic, title, page, pages, text}. An unknown topic is exit 2 with the topics listed in fix.
| TOPIC | COVERS |
|---|---|
check-failure |
Diagnosing a failed check and retrying only what changed. |
permissions |
A refused call: telling a denial from an approval request, and what to do next. |
authorization |
What existing authorization already covers, and when to ask again. |
testing |
Choosing, reusing and scheduling checks. |
recovery |
A denied daemon connection, a refused task start, a retry and a card move. |
deliver-recovery |
Repairing a failed commit, merge, push or landing. |
plan-format |
The fields and rules of a saved execution plan. |
review-format |
The Review sections, attention items and adversarial verdict a card carries. |
handoffs |
What a durable handoff records, and how to store it. |
Two verbs sit in the help table with no engine behind them. They exit 6 and name the plan that owns them.
No milestone is set for either. grid project autoconfigure <name> will drive the auto-configure flow the app already has, and grid workflow check <file> waits on a workflow document format that does not exist yet. See the pipeline.
Every command with a sub-command takes --json, as do status, doctor, demo and version. start, stop, restart, logs and open do not. Success prints {"ok":true,"command":"card.new","data":{…}}. Failure prints {"ok":false,"command":…,"error":{"code":…,"message":…,"fix":…,"detail":…}} to stdout even on a non-zero exit, so CI still gets the fix. The envelope is the CLI's own; daemon bodies go inside data.
| EXIT | CODE | MEANS |
|---|---|---|
| 0 | Done. | |
| 1 | failure |
The daemon did not answer, or something unclassified went wrong. A sandbox that denies loopback access to the daemon lands here too, with a fix that ends at grid help recovery. |
| 2 | usage |
A bad flag, an unknown command, a title over the cap. |
| 3 | not_found |
No card, project or route matched. |
| 4 | contract_not_satisfied |
A transition hook refused the move, or the daemon refused a plan or an execution step. fix carries the remediation sentence and detail the block record or the plan's problems. |
| 5 | needs_your_decision |
An ambiguous ref, a question with no Approve option, a demo that already exists. |
| 6 | not_built_yet |
A documented verb with no engine behind it. |
| 7 | timeout |
grid wait reached its --timeout with nothing changed. |