Skip to content
AndonDocs
GitHub
Look something up

The andon command

View as MarkdownThe same text, at this page's address plus .mdOpen in ClaudeAsk questions about this pageOpen in ChatGPTAsk questions about this page

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.

text
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

text
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

text
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

text
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

text
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

text
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

text
andon archive <KEY> [--json]

andon comment

text
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

text
andon comments <KEY> [--json]

A card’s comments, with their ids.

andon teams, andon projects

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

The names -t and -p take.

andon group, andon ungroup, andon groups

text
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

text
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.