rota verb reference

rota is the single binary behind every rota skill. Skills call it for all backlog, knowledge, plan, status, git and release bookkeeping, and you can call it directly when scripting against .rota/. There is no helper copy to refresh in a project. Install rota (see install).

rota item create --kind bugs --title "Crash on save" --tag P1 --desc "Why."
rota backlog list --json
rota knowledge query "Auth & Sessions"

Quick index

Verbs are not skills: skills are the /rota-* slash commands (see skills); these are the rota binary’s own verbs. Where to find the common ones:

• Start and set up. rota init scaffolds .rota/; rota setup (same section) adds the config walkthrough. rota config reads and changes settings. rota skills writes and refreshes the skills. rota update checks for a newer release. rota migrate moves the backlog or milestones.
• Bare rota. In a terminal it opens a palette. Enter on the preselected entry runs rota setup in a directory without .rota/ and launches the orchestrator in an initialized project. Outside a terminal it prints usage. See rota orchestrate.
• --ui. Opens a verb’s terminal screen instead of printing its result: rota config --ui, rota projects --ui, rota round status --ui (refreshes every 5 s), and read-only views for rota doctor, rota worker account list, rota backlog list, rota knowledge stats and rota decisions stats. Terminal only; refused with --json. Plain output never changes.
• Run a round. rota orchestrate starts the orchestrator. rota round takes the lease, assigns issues, waits, summarizes cost (round summary) and winds down. rota worker holds the slot registry and the merge gate (rota worker gate <PR> gates any open PR by number).
• Keep a round healthy. rota doctor preflights the machine. rota reap removes leftovers. rota layout folds panes into a split view or back into tabs. rota keepalive, rota limit, rota hook and rota statusline cover unattended rounds. rota verdict records review and QA verdicts.
• Agents and projects. rota agents write writes the role subagent files. rota projects (under rota init) lists the projects registered on this machine.

See parallel rounds and unattended rounds.

Conventions

• Global flags. --json prints one JSON envelope on stdout, -C <dir> runs as if started in <dir>, --repo <name> scopes a verb to an umbrella sub-repo, -h prints help for any group or verb.
• No prompts. rota never asks anything. A missing decision is exit 2 naming the flag. Skills do the asking. The exception is rota setup, which prompts only on a terminal.
• Bodies on stdin. Any flag that takes a file path also accepts - (--body-file -).
• Project root. Verbs walk up from the working directory to the nearest .rota/. Verbs such as rota init (with check and umbrella), rota setup, rota projects, rota version, rota update, rota doctor and rota skills run without one.
• Idempotent writes. A mutating verb reports changed: true|false. A no-op is exit 0.

Not a stable API across major versions, but --json shapes only change additively within one. Full rules: CLI conventions. Per-verb data shapes, exit codes and repo scope: verb contract. rota <group> --help lists a group’s verbs, rota <group> <verb> --help its flags.

Verbs

rota version

rota update

rota config

rota repo

rota id

rota item

rota backlog

rota summary

rota issues

rota status

rota refactor

rota migrate

rota knowledge

rota decisions

All writes target the umbrella .rota/DECISIONS.md, reject --repo, and refresh the decisions index. The body file for add / supersede holds the rule, *Why.*, **Forbids.** and **Permits.** in order; inline text and bullet lists are accepted. Existing optional paths comments are preserved. For amend, supply only the selected part’s contents, without its marker.

rota glossary

rota block

rota instructions

rota map

rota qa

rota milestone

rota plan

rota design

rota spike

rota proof

rota debug

rota worker

rota orchestrate

Bare rota with no verb does the same in an initialized project and runs rota setup in a directory that is not one. In your home directory (with no .rota/ there or above) it is a launcher instead: Projects is the default entry, Setup is hidden, and Config opens the global config. The agent comes from orchestrator.harness.

rota skills

rota round

The orchestrator’s verbs for a parallel round. All of them read and write .rota/workers.json and the round lease.

Request ids. round assign, round transfer, round reclaim, round pick, round return, round report, round tick, round escalate send, worker gate and worker train take --request-id <id> and keep a receipt per call in .rota/receipts.json (gitignored, pruned by round wind-down). Without the flag the verb mints an id and prints it as requestId in --json. A retry with the same id and the same inputs (arguments, the content of --settled-file/--body-file/--note-file/--reason-file, and for gate and train the head of each branch judged) returns the first result and applies nothing (replayed: true, changed: false). The same id with other arguments exits 4 with blockedBy: request-id. A gate or train that ends in a verdict (verify-failed and the like, exit 1) is finished, not pending: a replay returns the verdict with exit 1. This includes environmental verdicts (base-moved, verify-timeout, check-broke, merge-failed, ci-not-run): a retry under the same id replays the stored failure, it does not rerun. After a push the same id is refused (exit 4, blockedBy: request-id), since the head is part of the fingerprint. To rerun, make a fresh call without --request-id, after a push if the head should change. A call that failed part way (a flaky gh, a lost pane) records failedStage and residualResources, and its error hint names the stage and the id; the retry runs again and resumes from the stage that failed (resumedFrom in the result). A call that wrote nothing (exit 2 to 4, or --check-only) leaves no receipt.

After a lost response (a timeout, a broken pipe, a write | jq || write whose jq failed), run rota receipt show <request-id> [--json] with the id of the first call, never the same write again. It reads .rota/receipts.json and exits 0 with state: completed (the call applied; result holds the stored data), pending (it stopped part way; replay it with the same id and arguments) or absent. absent is not proof that nothing happened: a call still running, a pruned receipt, a call that wrote nothing or a receipt that failed to record all leave none, so inspect the affected state before you re-run.

round escalate check is read-only and has no id. Two concurrent calls with one id run the mutation once: the second waits on a claim lock (.rota/receipts.json.<hash>.lock, at most 10 minutes, then a retry error) and replays. A reused round tick id replays the first tick, so give each tick a fresh one. gate and train take the branch head from the gate’s own target resolution, so a queued or adopted PR gets a real head (a bare external PR’s head comes from the forge). A push under the same id is refused, not replayed.

A second round start is refused (exit 4) while another orchestrator holds the lease. round wait exits 1 on --timeout with data.timedOut: true, which is an answer, not a fault.

rota agents

Idempotent. Exit 4 when a target exists without the generated-by-rota header (nothing is written) or a role’s effort is one Codex cannot express. --check writes nothing and exits 1 when a file is missing or has drifted. See configuration.

rota doctor

Read-only, runs without .rota/. Exit 1 when any check fails; every failure carries a hint with the fix. See preflight.

rota reap

Previews by default. It never kills a running agent and never deletes work: a candidate that holds uncommitted changes or unmerged commits is listed with held and left alone. Exit 1 under --apply when a deletion failed. Exit 5, with nothing listed or deleted, when .rota/workers.json exists but does not parse; rota worker pool reap refuses the same way.

rota layout

split and tabs are remembered for the round (layout in .rota/workers.json): later spawns join the grid while it is split. A new round starts in tabs.

herdr only; a tmux or solo round is skipped. Moves live panes without restarting or typing into them, and never steals focus. See parallel rounds.

rota hook

install and uninstall are the ones you run; stop, prompt, session-start and guard are what Claude Code calls. Default scope is project-local (.claude/settings.local.json). install exits 4 rather than replace a statusline you already have unless you pass --wrap-statusline. stop, prompt and session-start always exit 0; guard exits 2 to refuse a worker’s command. install warns when the guard sits only in project-local scope, which worker worktrees do not read. See the worker guard.

rota statusline

A statusline command, not a query: it prints nothing of its own, always exits 0 and takes no --json. rota hook install --wrap-statusline sets it up around the statusline you have.

rota keepalive

run blocks for the life of the orchestrator. Exit 0 when it stopped on no-handoff or interrupted, 1 on max-restarts or breaker, 4 when the lease is held by someone else.

rota limit

keepalive run already runs the watcher; use watch for an orchestrator started another way. It refuses (exit 4) under a live supervisor or without the lease.

rota verdict

Verdicts are PASS, CONCERNS or FAIL (qa also takes INFRA-FAIL). They live in .rota/verdicts.json, which /rota-ship routes on.

rota tracker

rota git

rota review

rota ship

rota release

rota bugreport

A verb that fails with exit 70 writes a record by itself. See /rota-bugreport.

rota gate

A gated verb refuses with exit 4 (blockedBy: "manual gate") at every autonomy level unless --confirm and --confirm-note carry the human’s answer, and appends each approval to .rota/gate-audit.jsonl. See references/manual-gates.md.

rota init

Keeping this page current

The tables are generated from the usage lines in the verb contract and the summaries from rota <group> <verb> --help --json. When a verb changes, regenerate the row rather than editing prose around it.