CLI reference

Install it with npm i -g --allow-remote=root https://app.gaitro.com/cli.tgz. Every command accepts --json. gaitro --help prints this list.

Getting set up

Command	What it does
gaitro login [--server url]	Sign in through your browser.
gaitro login --device	No browser here (SSH, servers): enter a code on another device.
gaitro login --token <token>	For CI and scripts: a login made in Settings › Agents.
gaitro projects	The projects in your company.
gaitro open <company>/<project>	A working copy under ~/gaitro/, made once and reused (prints its folder).
gaitro clone <company>/<project> [dir]	Get a working copy where you choose.
gaitro init [--name <name>] [--tenant <tenant>]	Bring an existing git repo in (its HEAD becomes trunk).

Already building? Bring it to Gaitro

Command	What it does
gaitro overlap	Is anyone else working on what you've changed? Changes nothing.
gaitro push [-m "<what you were asked to do>"] [--check <sentence>]…	Open a draft from this work, or save the next checkpoint.

The workflow

Command	What it does
gaitro intent "<request>" [--plan <step>]… [--check <sentence>]… [--claim <symbol>[:read|body|shape]]…	Open a draft for a request, before editing.
gaitro intent --take <n>	Take a request someone made in the app.
gaitro requests	Requests waiting for an agent.
gaitro attach <n>	Work on an existing draft from this working copy.
gaitro symbols [search]	Find symbols to claim.
gaitro claim <symbol>… [--wait | --ask "<why>" | --narrow]	Claim symbols before editing them.
gaitro release [<symbol>…]	Give claims back.
gaitro status [--full]	Checks, blockers and the next step (--full: every claim).
gaitro wait [--timeout <seconds>]	Return when this draft's checks have finished.
gaitro sync [-m "<message>"] [--done <step>]	Checkpoint, safety checks, then the affected checks.
gaitro ready [--summary "<for someone who doesn't read code>"]	Mark the draft done, which runs the full suite.
gaitro ship [--summary "..."]	The person said ship it: goes live once checks pass.
gaitro safety ok <id> --reason "..." [--confirmed]	Answer a safety finding (logged).
gaitro replay [--continue | --abort]	Re-apply this draft onto the latest version.
gaitro choice ["<question>"]	Hand a conflict you can't resolve to a person.
gaitro watch [--until <event,…>]	Stream events for this draft.
gaitro discard	Drop this draft.

Checks

Command	What it does
gaitro check add "<sentence>" [--run "<cmd>"] [--file <test file>]	Add a check, with its test if it's written.
gaitro check compile <handle> --run "<cmd>" [--file <test file>]	Link a check to the command that runs its test.
gaitro check logs <handle>	A check's latest full output.
gaitro check edit <handle> [--sentence] [--run]	Reword or re-point a check this draft added.
gaitro check remove <handle>	Drop a check this draft added.
gaitro check setup "<command>"	Runs once before each run's checks (npm ci, a build).
gaitro check env	What checks run in: OS, Node, tools, network, env vars.
gaitro check run <handle> [--setup]	Run a check here, the way the server does.

Knowledge

Answers other drafts already proved, looked up when a check fails. See Knowledge.

Command	What it does
gaitro knowledge search "<error or package>" [--package <name> --from <v> --to <v>]	Ranked answers.
gaitro knowledge show <answer-id>	The full answer; a public one counts as a lookup.
gaitro knowledge questions	This project's open questions.
gaitro knowledge ask --package <name> --error "<message>" [--from <v> --to <v>]	Ask before a check has failed.
gaitro knowledge claim <symbol>	What's known about the packages behind a claim.
gaitro knowledge share <lesson-id>	Share a kept lesson (owners; safety checks still apply).

Secrets

Command	What it does
gaitro secret set <NAME> [--env preview|production]	Store a secret; the value is read from stdin and never printed back.
gaitro secret list	The names of this project's secrets.

Anything that needs a secret runs as a check, where the server injects it.

MCP

Command	What it does
gaitro mcp	Start the MCP server (stdio). See the MCP reference.