Docs

globals

Apply to every command.

gears -a <label> --json <command>

-a / --agent   act as this label (else $GEARS_AGENT, else login --label, else local)
--json         same shape the MCP tools return
-v / --version

gears login

Save a device token, register the workspace, report what there is to pull. Nothing else.

gears login [--email …] [--label …] [--api …]

gears login --email you@example.com
gears login --label claude-local

gears logout

Revoke this device token and forget it.

gears logout [--api …]

gears whoami

API host, token health, workspace, label in use.

gears whoami

gears init

Create a workspace in this directory. One .gears at the root; refused inside an existing workspace.

gears init [--slug …] [--prefix …] [--offline]

gears init --prefix GRS

gears migrate

Upgrade a v2 .gears tree to v3. Renames old tree to .gears_v2, inits, copies markdown as free-- artifacts.

gears migrate [dir] [--dry-run] [--offline]

gears status

Cold-start packet. Run first every session.

gears status [--full] [--json]

gears status
gears status --full

gears sync

Push local changes, then pull and apply.

gears sync [--api …]

gears run

Local MCP over stdio. Live card board while running. Optional periodic full sync.

gears run [--dir …] [--sync-interval N]

gears run --dir /path/to/workspace
gears run --sync-interval 5

gears watch

Follow the live board. One line per card change. Needs login and one sync.

gears watch [--json]

gears export

Dump the local SQLite record as JSON.

gears export [--out file]

gears projects list

Print .gears/projects.yaml.

gears projects list

gears projects scan

Find git repos under projects/, record them. Gone repos marked missing, never dropped.

gears projects scan [--offline]

gears people

Workspace members and their agent labels. Ids for desk send --assign.

gears people

gears members

Members and pending invites for this workspace.

gears members [--all]

gears invite

Invite an existing account by email. Owners only for --role owner.

gears invite <email> [--role member|owner]

gears invite bob@example.com
gears invite bob@example.com --role owner
gears invite revoke <id>

gears invites

Invites sent to me, any workspace.

gears invites

gears invites accept <id>
gears invites decline <id>

gears desk list

Open items for you or anyone.

gears desk list [--all] [--type info|ask|event|work|handoff]

gears desk send

Place an item. Type is lifecycle: info/ask/event/work/handoff.

gears desk send <text> -t <type> [--to label] [--assign id] [--ref …]

gears desk send -t info --to claude-local "API port is 8220."
gears desk send -t ask --to grok-web "Ready to review?"
gears desk send -t handoff "Tried X. Result Y. Next: Z."
gears desk send -t work --assign <user-id> "Review the schema."

gears desk read

Read one item. info closes when read.

gears desk read <id>

gears desk answer

Close an ask with a reply.

gears desk answer <id> <text>

gears desk done

Close a work item.

gears desk done <id>

gears desk dismiss

Close an event.

gears desk dismiss <id>

gears desk clear

Close open items. Default: mine. --all: whole workspace.

gears desk clear [--mine|--all]

gears card shapes

Catalog: types, sections, sizes, priorities. Read before first card new.

gears card shapes

gears card new

Create a card. Needs the type's top-line and at least one --accept.

gears card new <title> -t <type> --accept … [flags]

gears card new "Login with Google" \
  --as-a "staff" --i-want "sign in with Google" --so-that "no second password" \
  --accept "Google button shows, proven by a screenshot" --size S --priority P2

gears card new -t defect "Invites fail" \
  --set defect.symptom=fail --set defect.expected=sent --set defect.actual=500 \
  --accept "Send succeeds"

gears card list

The board.

gears card list [--state …] [--type …] [--tag …] [--assignee me] [-q …] [--closed|--all]

gears card show

Full card: sections, brief, comments, links, checklists, activity.

gears card show <key>

gears card claim

Assign to me and move out of the default state.

gears card claim <key>

gears card move

Move to a state. Optional position.

gears card move <key> [state] [--pos top|bottom|after:<key>]

gears card update

Change only the flags you pass. Still must pass the type rule.

gears card update <key> [--title …] [--set …] [--accept …] …

gears card comment

Add evidence. Body stays the original text.

gears card comment <key> <text>

gears card tag

Add or remove tags.

gears card tag <key> [+tag|-tag|tag …]

gears card link

Link cards or a URL ref.

gears card link <key> [target] [--kind blocks|blocked-by|related|ref] [--url …]

gears card check

Human checklists (UAT).

gears card check <key> [items…] [--op add|item|tick|untick|remove] [--list …]

gears card check GRS-3 "Button shows" "Revoked user refused"
gears card check GRS-3 --op tick 1

gears card close

Take off the board without deleting. list --closed still shows it.

gears card close <key> [--note …]

gears card reopen

Put a closed card back.

gears card reopen <key> [--note …]

gears card delete

Soft-delete. Number never reused.

gears card delete <key>

gears card states

Swimlanes: list, add, rename, reorder, remove, default, terminal, wip.

gears card states [list|add …|rename …|…]

gears card activity

Recent board events, newest first.

gears card activity

gears artifact new

Row first, then a file seeded from its shape. Prefixes: arch, adr, story, idea, index, free, runbook, shape.

gears artifact new <prefix> <title> [--project …]

gears artifact new adr "Workspace root only"
gears artifact new story "Desk handoff"

gears artifact list

All artifacts with tags and shape status. Reconciles first.

gears artifact list [--tag …]

gears artifact tag

Tags live on the row, never in the file.

gears artifact tag <file|id> <+tag|-tag>…

gears artifact validate

Check against shapes in force.

gears artifact validate [file]

gears artifact reconcile

Make rows and files agree. Runs on list and status too.

gears artifact reconcile

gears artifact delete

Row and file together. Sync soft-deletes remotely.

gears artifact delete <file|id>

gears artifact shapes

Shapes in force for this project.

gears artifact shapes

gears arch

Print arch--primary.md. Status always shows it.

gears arch

gears arch edit

Open in $VISUAL/$EDITOR, then reconcile.

gears arch edit

gears arch init

Write the stub if missing.

gears arch init

gears session new

Append one entry. Kinds: done, decision, problem, next.

gears session new <text> -k <kind> [--project …]

gears session new -k done "GRS-28 shipped; commit 3dd3b70"
gears session new -k next "Pick GRS-37 next."

gears session list

Recent entries, oldest first. Every agent folded by time.

gears session list [--days 3]

gears runbook list

Official runbooks (frozen or editable), this workspace's adopted copies, and local drafts. MCP runbook_list.

gears runbook list

gears runbook show

One runbook in full: each step's kind, params, tool and the evidence that proves it. MCP runbook_show.

gears runbook show <slug|ref>

gears runbook abilities

The step-kind catalog: kinds, tools, params, evidence kinds. MCP runbook_abilities.

gears runbook abilities

gears runbook adopt

Copy an official runbook into the workspace. Frozen copies run the official steps. MCP runbook_adopt.

gears runbook adopt <ref> [--as name]

gears runbook adopt ticket-development

gears runbook edit

Change an editable copy: title, description, or the whole step list. MCP runbook_edit.

gears runbook edit <slug> [--title …] [--description …] [--steps-file steps.json]

gears runbook unadopt

Remove an adopted copy, frozen or editable. Started runs keep their steps. MCP runbook_unadopt.

gears runbook unadopt <slug>

gears runbook start

Start a run on gears-api: an official runbook by ref (today ticket-development; no adoption needed), an adopted slug, or inline steps. MCP runbook_start.

gears runbook start <slug> [--card <card-key>] [--step id[:kind]] [--key …]

gears runbook complete

Complete the current step with evidence that exists in the workspace. A refusal leaves it current. MCP runbook_step_complete.

gears runbook complete [kind:ref …] [--run …] [--step …] [--note …]

gears runbook complete session:1a2b3c4d card:GRS-12:Testing commit:abc1234

gears runbook next

What to do now on a run: the current step with its executor (system or agent), instructions, and who it waits on (agent, system, human). Several running runs are listed to pick from. MCP runbook_next.

gears runbook next [run]

The agent loop

How a local agent drives a run: the run decides the next step, the agent does it. Resume first with runbook_runs (mine, running); else runbook_start. Then runbook_next, do the work, runbook_step_complete with evidence, repeat until finished. waitingOn system: the run moves or comments on the card itself; wait. waitingOn human: an approval only a person gives on the run page or its desk item; never complete it. Two human gates: designing the ticket is outside runs; the audit approval is inside.

runbook_runs → runbook_start → runbook_next → (work) → runbook_step_complete → runbook_next …

runbook_runs  {"mine": true, "status": "running"}
runbook_start {"runbook": "ticket-development", "cardKey": "GRS-12"}
runbook_next  {"run": "run-0199..."}   # waitingOn: system (card to In Progress)
runbook_next  {"run": "run-0199..."}   # waitingOn: agent (git.branch)
runbook_step_complete {"run": "run-0199...", "evidence": [{"kind": "commit", "ref": "3f2a9c1"}]}
runbook_next  {"run": "run-0199..."}   # ... until "finished": true

gears runbook skip

Skip the current step. Reason required; it stays on the run. MCP runbook_step_skip.

gears runbook skip --reason … [--run …] [--step …]

gears runbook status

One run's steps from the record (--refresh asks the runbook service), or the list. MCP runbook_status.

gears runbook status [run] [--refresh] [--status …] [--card …]

gears runbook runs

Runs with current step, progress, agent and card. Works without the runbook service. MCP runbook_runs.

gears runbook runs [--mine] [--by label] [--runbook …] [--card …] [--status …] [--limit n] [--cursor …]

gears runbook new

Local draft (runbook--<slug>.yaml), authored with the step commands. Not runnable as it stands.

gears runbook new <title> [--target card|repo|none]

gears runbook copy

Copy a builtin or another project's draft.

gears runbook copy <slug> [--from dir] [--as title]

gears runbook update

Change a draft's title or target. Slug stays.

gears runbook update <slug> [--title …] [--target …]

gears runbook delete

Delete a local draft.

gears runbook delete <slug>

gears runbook step

Author a draft's steps: add, update, remove, move.

gears runbook step add|update|remove|move <slug> …

gears completion

Shell completion scripts.

gears completion [bash|zsh|fish|powershell]

gears help

Help for any command.

gears help [command]