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. 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 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.
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.
andon keys
The member device keys whose signed commands this machine accepts (see
signatures).
| 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).
| 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. 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. 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.
