# The andon command

`andon` is the machine agent's command line: it enrolls a machine with a board, runs the daemon, sets the machine's
policy, and reads and changes cards from a terminal. Run `andon` with no arguments (or `andon --help`) to print the
same list in short.

Every command and flag below is checked against the code by a test (`apps/agent/src/reference-docs.test.ts`), which
fails when the CLI gains one this page doesn't have.

## Global options

| Option | What it does |
|---|---|
| `--profile <name>` | Run the command against another agent on this machine, one enrolled with a different board. `andon profiles` lists them. Also `--profile=<name>`. It goes before the command: `andon --profile work status`. |
| `--help` | Print the command list. `andon help` does the same. |
| `--version`, `-v` | Print the agent's version and protocol version, like `andon version`. |

## Set up and run the machine

### `andon setup`

Enrolls this machine with a board, then installs the background service and runs `andon doctor`. Run it again on an
enrolled machine to change its policy with a flag; without one it keeps the policy as it is.

```
andon setup --url <board> [flags]
```

| Flag | What it does |
|---|---|
| `--url <board>` | The board's address. Needed the first time. |
| `--code <install code>` | Enroll with an install code from the board instead of approving the device in a browser. |
| `--other-board add\|move\|keep` | This machine already has an agent for another board. `add` enrolls a second agent beside it, `move` stops the first and sets its config aside, `keep` stops here. Asked when there is a terminal and no flag. |
| `--no-browser` | Don't open the browser for the device approval: the command prints the link. |
| `--no-service` | Don't install the background service (and don't expect one in the doctor check). |
| `--preset locked\|standard\|open` | Apply a [policy preset](https://andon-docs.pages.dev/reference/policy.md#presets). Without it, a new machine gets Open; Enter at the question picks Open too. |
| `--trust-org` | Run any recipe from the org. |
| `--approve-current` | Approve the org's current recipes on this machine; a new or edited one needs approving here. |
| `--allow-auto-merge`, `--no-auto-merge` | Whether this machine may merge a reviewed pull request when its team turns auto merge on. |
| `--scan-roots a,b` | The folders to scan for git repositories, comma-separated. A folder named here that is outside the policy's workspace roots is added to them without asking. Without this flag, setup asks about each such folder at a terminal (Enter is yes) and leaves it out when there is no terminal. |
| `--no-scan` | No repository scan on this machine. |
| `--direct` | Never use Orca: runs use git worktrees and tmux. |
| `--tunnel tailscale\|cloudflare\|off` | Which tunnel carries previews and the direct terminal. Asked once when there is a terminal and no flag. |
| `--install-claude`, `--no-install-claude` | Install Claude Code (and sign it in) when the Claude desktop app is here but its CLI isn't. |
| `--linger`, `--no-linger` | Linux: keep the agent running when you log out (`loginctl enable-linger`). |
| `--hook-port <port>` | The local port the agent's hook server listens on (default 7777). `ANDON_HOOK_PORT` does the same. |
| `--credential-backend keychain\|secret-service\|file` | Where the machine's sign-in is kept. Default: the Keychain on macOS; on Linux, the Secret Service when there is a session bus and `secret-tool`, else a file. `ANDON_CREDENTIAL_BACKEND` does the same. |
| `--yes`, `-y` | Answer every question with its default, and ask nothing. A new machine gets the Open preset. It never adds a folder to the workspace roots on its own. |

### `andon enroll`

The enrollment part of `andon setup` alone: no service install and no doctor check. It takes the same flags.

### `andon agent`

Runs the daemon in the foreground. The service runs this; you rarely need to.

### `andon doctor`

Checks what the agent needs (its config, Node, Orca or tmux, Claude Code, git, the optional `gh` and `ffmpeg`, the
service, the workspace roots) and prints a fix for each problem. Exits 1 when something required is missing.
It also prints the last time the agent's tmux server went away with runs in it (when, how many runs, the server's
process id and what the agent could tell about why); that line never fails the check.

### `andon install-service`, `andon uninstall-service`

Installs (or restarts) the background service: a LaunchAgent on macOS, a systemd user unit on Linux. `uninstall-service`
stops and removes it; the config stays.

| Flag | What it does |
|---|---|
| `--linger`, `--no-linger` | Linux: keep the agent running when you log out, or not. Without either, you're asked when there is a terminal. |
| `--yes`, `-y` | Linux: without asking, turn linger on when there is no display. With a display it stays off. |

### `andon status`

Prints this machine's name, board, launcher and version, and the other agents on the machine.

### `andon profiles`

Lists the agents on this machine, one for each board, with the `--profile` name to reach each.

### `andon version`

Prints the agent's version and protocol version.

### `andon update`

Verifies the installed agent against the board's signed build and installs it when it differs. The agent also checks
once a day unless [`auto-update`](https://andon-docs.pages.dev/reference/policy.md#subcommands) is off.

| Flag | What it does |
|---|---|
| `--trust-board` | No release key is pinned on this machine: install the board's build on its checksums alone. |

### `andon mcp`

The MCP server a run's Claude Code session starts. It isn't for people: see [MCP tools](https://andon-docs.pages.dev/reference/mcp-tools.md).

## Policy, keys and repositories

### `andon policy`

Prints and changes this machine's local policy, such as `andon policy auto-merge off` or
`andon policy extra-args --clear-retired`. Every subcommand and key is on [the policy page](https://andon-docs.pages.dev/reference/policy.md).

### `andon keys`

The member device keys whose signed commands this machine accepts (see
[`signatures`](https://andon-docs.pages.dev/reference/policy.md#subcommands)).

| Subcommand | What it does |
|---|---|
| `andon keys` or `andon keys list` | Approved keys, and keys registered on the board but not approved here. |
| `andon keys approve <fingerprint>` | Trust a device key. Give the fingerprint the board shows on that device (at least 16 characters). |
| `andon keys remove <fingerprint>` | Stop trusting a key (at least 8 characters of its fingerprint). |

### `andon repos`

Where the agent looks for git repositories.

| Subcommand | What it does |
|---|---|
| `andon repos` or `andon repos list` | The mode (Orca or direct), the scan roots, and other folders it found. |
| `andon repos add <path>` | Scan this folder too. A folder outside the policy's workspace roots asks first (Enter is yes); `--yes` (`-y`) confirms it without asking. |
| `andon repos remove <path>` | Stop scanning a folder. |

### `andon tunnel`

Previews of sites a run serves, and the board's direct terminal.

| Subcommand | What it does |
|---|---|
| `andon tunnel` or `andon tunnel status` | The tunnel and whether it's ready. |
| `andon tunnel tailscale` | Use Tailscale. |
| `andon tunnel cloudflare` | Use a Cloudflare quick tunnel. |
| `andon tunnel off` | No tunnel: previews are off. |

| Flag | What it does |
|---|---|
| `--no-terminal` | Keep the direct terminal off; only previews use the tunnel. |
| `--terminal` | Turn the direct terminal back on. |

The agent restarts to apply the change.

### `andon accounts`

Claude Code, Codex and Gemini CLI logins on this machine. A team picks one on the board.

| Subcommand | What it does |
|---|---|
| `andon accounts` or `andon accounts list` | The accounts, their ids and whether each is signed in. |
| `andon accounts add claude\|codex\|gemini <name>` | Add an account with a config folder of its own, then sign in to it. |
| `andon accounts login claude\|codex\|gemini <name>` | Sign in to an account again. |
| `andon accounts remove claude\|codex\|gemini <name>` | Forget an account. |

| Flag (`add`) | What it does |
|---|---|
| `--current` | Use the machine's own login rather than a new folder. |
| `--dir <path>` | Use this folder as the account's config folder. Never `~/.gemini`. |
| `--no-login` | Don't sign in now. |
| `--no-share` | Claude only: don't link the settings shared with `~/.claude` into the account. |

### `andon llm`

Machine mode: model calls the app hands this machine (`LLM_PROVIDER=machine`, or the org's setting) run here on the
Vercel AI SDK with this machine's own key. Turn it on with `andon policy llm-serve on`. Keys stay in this machine's
credential store (or the daemon's `ANTHROPIC_API_KEY` / `GEMINI_API_KEY` / `AI_GATEWAY_API_KEY`); the board only sees
that one is there.

| Subcommand | What it does |
|---|---|
| `andon llm` or `andon llm status` | Whether machine mode is on, the backend, and which keys this machine holds. |
| `andon llm key anthropic\|gemini\|gateway` | Save a key, read from stdin (`andon llm key gemini < key.txt`) or from `--key-env`; `--clear` removes it. |
| `andon llm backend auto\|anthropic\|direct\|gateway` | Which key a call uses: `auto` is Claude with an Anthropic key, else Gemini with a Gemini key, else the gateway. |

### `andon providers`

Model endpoints this machine can reach, such as OpenRouter, a local Ollama or LM Studio. Keys stay in this machine's
credential store; the board only sees that a key is there.

| Subcommand | What it does |
|---|---|
| `andon providers` or `andon providers list` | The providers, whether each has its key, and the models each serves. |
| `andon providers add <slug>` | Add a provider. A known slug fills in its address and wire form. |
| `andon providers key <slug>` | Save its key, read from stdin (`andon providers key openrouter < key.txt`) or from `--key-env`. |
| `andon providers remove <slug>` | Forget the provider and its key. |

| Flag | What it does |
|---|---|
| `--url <url>` | `add`: the provider's base address. |
| `--name <name>` | `add`: a display name. |
| `--wire anthropic_messages\|openai_chat\|openai_responses` | `add`: the request format it speaks. |
| `--model <id>` | `add`: a model it serves. Repeat it for more. |
| `--key-env <VAR>` | `key`: read the key from this environment variable. |
| `--clear` | `key`: remove the saved key. |

### `andon harness`

Harnesses: a bundle of skills and a pipeline outline, imported and approved at their content hash.

| Subcommand | What it does |
|---|---|
| `andon harness` or `andon harness list` | Imported harnesses, their hash and whether each is approved here. |
| `andon harness add <path\|git-url>` | Import one from a folder or a git URL, and record it on the board. |
| `andon harness approve <slug>` | Approve it here, so runs may use it. A changed bundle needs approving again. |
| `andon harness remove <slug>` | Forget it on this machine. The files stay. |

| Flag (`add`) | What it does |
|---|---|
| `--ref <sha>` | The git commit to import. |
| `--approve` | Approve it in the same step. |
| `--no-register` | Don't record it on the board. |

### `andon memory`

What the team has learned (team memory, on the board), and what a repository remembers (its `.andon/` folder,
[format](https://andon-docs.pages.dev/reference/andon-directory.md)).

| Subcommand | What it does |
|---|---|
| `andon memory show [path]` | The repository's live memory, read from the `.andon/` files of the checkout at `path` (default: here). No board needed. |
| `andon memory` or `andon memory list` | The team's memory entries, newest first. |
| `andon memory search <words>` | Search the active entries. |
| `andon memory reflect <run-id>` | Propose lessons from a finished run. They wait on the board for a person to accept. |

| Flag | What it does |
|---|---|
| `--root <dir>` | `show`: read `.andon/` from this folder, for a team that keeps memory outside the repository. |
| `--instance <repo-id>` | `show`: read this machine's own copy for a repository. |
| `--team <id>` | `list`, `search`: one team only. |
| `--status active\|proposed` | `list`: only entries in this state. |
| `--limit <n>` | `list` (default 50), `search` (default 10): how many. |
| `--apply` | `reflect`: record the lessons as active at once, without the board. |

## Cards

These commands read and change cards on the board this machine is enrolled with. A `<KEY>` is a card's key (`WEB-12`),
its id, or the key of its tracker issue.

Most of them use the [public API](https://andon-docs.pages.dev/reference/api.md). With a personal API token saved (`andon api-token`) they act as you. Without one they use this machine's
own sign-in, which reads the org's cards but can't change them: `andon edit`, `move`, `archive`, `unarchive` and
`comment` then answer `not allowed (403)`, while `andon add`, `group` and `run` work either way. Every command that
takes `--json` prints the API's answer instead of text.

### `andon add`

```
andon add "title" [-n notes] [-t team] [-p project] [-g group|new] [-r recipe] [-T template] [-u url] [-a file]… [-c column] [--priority 0-3] [-l label]… [--due YYYY-MM-DD] [--estimate n] [--json]
```

Adds a card to the Backlog through the [capture endpoint](https://andon-docs.pages.dev/reference/capture-api.md). A title is optional when you give a URL or a
file.

| Flag | What it does |
|---|---|
| `-n`, `--notes <text>` | The card's notes. |
| `-t`, `--team <name>` | Its team. |
| `-p`, `--project <name>` | Its project. A project alone brings its team. |
| `-g`, `--group <group\|new>` | Join an open PR group by name or id, or `new` for a planned group of its own. Needs `-t` or `-p`. |
| `-r`, `--recipe <slug>` | Its recipe. Leave it off to let the board pick. |
| `-T`, `--template <name>` | Fill it from a card template. |
| `-u`, `--url <url>` | A link the card is about. It becomes one of the card's links. |
| `-a`, `--attach <file>` | Attach a file. Repeat for more: up to 10 files, 25 MB each, 30 MB in all. |
| `-c`, `--column <column>` | `backlog`, `ready`, `working`, `review` or `done`. `working` starts a run. |
| `--priority 0-3` | None, low, high or urgent. |
| `-l`, `--label <label>` | A label. Repeat for more. |
| `--due YYYY-MM-DD` | Its due date. |
| `--estimate <n>` | Its estimate in points. |
| `--json` | Print the reply as JSON. |

`--column`, `--priority`, `--label`, `--due` and `--estimate` need the portable server.

### `andon capture-token`

Saves the capture token `andon add` sends. The token is read from the terminal (hidden) or a pipe, never from an
argument. `--clear` removes it. `ANDON_CAPTURE_TOKEN` wins over the saved token. On the portable server `andon add`
needs no capture token: it uses the machine's own sign-in.

### `andon api-token`

Saves a personal API token (`andon_pat_…`, made under **Settings → Connections → Developer → API tokens**). Card
edits, moves and comments need it, and then show as you. Read like the capture token; `--clear` removes it. `ANDON_API_TOKEN` wins over the saved
token.

### `andon list`

```
andon list [-t team] [-p project] [-c column] [-q '<filter>'] [--all] [--json]
```

The board's cards by column. Done cards are left out unless you pass `--all`, `-c done` or `-q`.

| Flag | What it does |
|---|---|
| `-t`, `--team <name>` | One team. |
| `-p`, `--project <name>` | One project. |
| `-c`, `--column <column>` | One column: `backlog`, `ready`, `working`, `review` or `done`. |
| `-q`, `--query '<filter>'` | A filter in the board's filter bar language: `-q 'label:bug priority:>=high'`. |
| `--all` | Include Done. |
| `--json` | Print JSON. |

### `andon show`

```
andon show <KEY> [--comments n] [--json]
```

A card in full: its fields, notes, latest run and recent comments. `--comments n` sets how many comments.

### `andon edit`

```
andon edit <KEY> [--title …] [-n notes | --notes-file f | --append-notes …] [--priority 0-3] [-l label]… [--unlabel label]… [-p project] [--owner me|<id>] [--due YYYY-MM-DD] [--estimate n] [--clear notes|project|owner|due|estimate|labels]… [--json]
```

| Flag | What it does |
|---|---|
| `--title <text>` | A new title. |
| `-n`, `--notes <text>` | Replace the notes. |
| `--notes-file <file>` | Replace the notes with a file's text. |
| `--append-notes <text>` | Add to the notes. |
| `--priority 0-3` | A new priority. |
| `-l`, `--label <label>` | Add a label. Repeat for more. |
| `--unlabel <label>` | Remove a label. Repeat for more. |
| `-p`, `--project <name>` | Move it to another project. |
| `--owner me\|<id>` | Give it to someone. |
| `--due YYYY-MM-DD` | A due date. |
| `--estimate <n>` | An estimate. |
| `--clear <field>` | Empty `notes`, `project`, `owner`, `due`, `estimate` or `labels`. Repeat for more. |
| `--json` | Print the card as JSON. |

### `andon move`

```
andon move <KEY> <backlog|ready|working|review|done> [--top] [--json]
```

Moves a card. Into `working` starts a run. `--top` puts it at the top of the column.

### `andon archive`, `andon unarchive`

```
andon archive <KEY> [--json]
```

### `andon comment`

```
andon comment <KEY> "text" | -F file [--reply-to <comment id>] [--json]
```

| Flag | What it does |
|---|---|
| `-F`, `--file <file>` | Take the comment from a file. |
| `--reply-to <id>` | Reply in a comment's thread. `andon comments` shows the ids. |

### `andon comments`

```
andon comments <KEY> [--json]
```

A card's comments, with their ids.

### `andon teams`, `andon projects`

```
andon teams [--json]
andon projects [-t team] [--json]
```

The names `-t` and `-p` take.

### `andon group`, `andon ungroup`, `andon groups`

```
andon group <KEY…> [--name <name>] [--into <group>]
andon ungroup <KEY>
andon groups [-p project] [-t team] [--all]
```

A PR group is cards that ship in one pull request. `andon group` makes a planned group of two or more cards;
`--into <group>` adds cards to an existing group instead, and `--name` (`-n`) names a new one. `andon ungroup` takes a
card out of its group. `andon groups` lists the open groups, or every group with `--all`.

### `andon run`

```
andon run <KEY | group> [-p project] [--retry | --continue "text"] [--json]
```

Runs a card now (it moves into Working), or a planned group. A card in a planned group runs its whole group.

| Flag | What it does |
|---|---|
| `-p`, `--project <name>` | Look the group's name up in this project. |
| `--retry` | Run the card's last run again. |
| `--continue "text"` | Send its session a follow-up. |
| `--json` | Print JSON. |

## Environment

The variables the agent reads are on [the environment page](https://andon-docs.pages.dev/reference/env.md#the-agent).
