# CLI reference

> Every gaitro command: logging in, opening projects, the draft workflow, checks, Knowledge and secrets. Every command accepts --json.

Source: https://gaitro.com/docs/cli

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](/docs/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](/docs/mcp). |