runbooks / command
Run runbooks
Runs runbooks: ui ones guided, headless, headed, in Claude in Chrome or as a prompt for the Chrome extension, once per screen size, comparing each linked screen with its design; api ones through their test script
❯ /runbooks:run <id...> | --capability x | --affected [base] [--mode guided|headless|headed|chrome|prompt|script|test] [--steps S01,S02] [--role a,b] [--case a,b] [--merge] [--record] [--import <file|text>] [--waive S03] [--model <model>]❯ $runbooks:runbooks-run <id...> | --capability x | --affected [base] [--mode guided|headless|headed|chrome|prompt|script|test] [--steps S01,S02] [--role a,b] [--case a,b] [--merge] [--record] [--import <file|text>] [--waive S03] [--model <model>]Parameters
Select runbooks one way: ids, --capability or --affected. ui runbooks run in the browser, once per viewport they list; api runbooks run through their test script, which /runbooks:to-test writes or adopts first when it is missing. Placeholders, deprecated and invalid runbooks are skipped and named in the summary. /runbooks:ui shows the results by capability.
| Parameter | What it does |
|---|---|
<id...> |
One or more runbook ids, separated by spaces. |
--capability <x> |
Every runbook of one capability. |
--affected [base] |
The runbooks the changes since base touch. base defaults to git.base. |
--mode <mode> |
Who drives the browser for ui runbooks. Without it, the command asks; there is no default. api runbooks ignore it and always run through their test script. guided: you act and give each step's state. headless / headed: the agent, through the Playwright MCP server, without or with a visible window. chrome: the agent, through Claude in Chrome; you sign in first. prompt: writes a prompt to paste into the Claude in Chrome extension. script: a temporary Playwright script, the fallback when an MCP server cannot start. test: the project's test command, for a runbook whose script has one test per step. |
--steps S01,S02 |
Run only these steps. The run is partial: it gets a report (local, in _runs/), but status and last_run stay as they are, unless --merge. |
--role editor,viewer |
With role tracking on: run only these roles of each runbook. Like --steps, it makes the run partial, and status and last_run stay as they are, unless --merge. review always stays. A role the runbook does not run is reported and skipped. |
--case a,b |
On a runbook with cases: run only these cases. It makes the run partial, like --role. A role that runs once builds the first selected case. A case the runbook does not run is reported and skipped. See contexts. |
--merge |
With --steps, --role or --case: write the cells this run covered into last_run and keep the others, then recompute status. Alone, the run is a full run, and the command says so once. review stays as it is. |
--record |
Run the selection against the live upstream API and save each response as a fixture of its runbook and step, for mocked runbooks. Needs a browser mode: guided, headless, headed or chrome. create and update call it. See upstream mode. |
--waive S03,S04 |
api runbooks only: record these steps as waived. Their tests still run, but their outcome is ignored. The command asks for the reason before the run. |
--import <file or text> |
Record the reply of a prompt run, from a file or pasted text. When the prompt run used --merge, type --merge again here; without it, the import of a partial run leaves last_run as it is. |
--model <m> |
Run every group of this run on one model: inline (in the main session), haiku, sonnet, opus or fable. Without it, each group of runbooks with the same mode and flags takes its row of the models table: by default run --mode guided runs inline, run --mode test, run --mode prompt and run --import on haiku, and every other mode on sonnet. Forcing a model turns off escalation: the sub-agent writes or fixes a missing script itself instead of handing it to to-test. On Codex, the values are inline, inherit (a sub-agent on the session's model) or a model ID the session supports, and the table is codex.models, where every row that is not inline defaults to inherit. See models. |
/runbooks:run billing.issue-invoice # one runbook, asks the mode
/runbooks:run billing.issue-invoice billing.cancel-invoice # several runbooks
/runbooks:run --capability billing # a whole capability
/runbooks:run --affected # touched since git.base
/runbooks:run --affected origin/main # touched since origin/main
/runbooks:run billing.issue-invoice --mode guided # you click, you judge
/runbooks:run billing.issue-invoice --mode headless # agent, no window
/runbooks:run billing.issue-invoice --mode headed # agent, visible window
/runbooks:run billing.issue-invoice --mode chrome # agent, in your Chrome
/runbooks:run billing.issue-invoice --mode prompt # prompt for the extension
/runbooks:run billing.issue-invoice --mode script # temporary Playwright script
/runbooks:run billing.issue-invoice --mode test # its script, one test per step
/runbooks:run billing.issue-invoice --steps S03,S04 # only some steps
/runbooks:run billing.issue-invoice --role editor,viewer # only some roles
/runbooks:run clients.edit-client --case vip-team,regular # only some cases
/runbooks:run billing.issue-invoice --steps S03 --merge # rerun one step, keep the others in last_run
/runbooks:run billing.issue-invoice --record --mode headless # record fixtures from the live API
/runbooks:run billing.create-invoice --waive S03 # api runbook, ignore one step's test
/runbooks:run billing.issue-invoice --import .runbooks/reply.md # a prompt reply, as a file
/runbooks:run billing.issue-invoice --import "<pasted reply>" # or pasted
/runbooks:run --affected --mode headless # mix a selection and a mode
/runbooks:run --affected --mode test --model sonnet # every group on sonnet, no escalation