The runbook language
A runbook is one YAML document: metadata says what it is, spec says what
it does. Only IDs are required, so the smallest runbook is four lines:
metadata: { id: hello }spec: steps: - id: say_helloThat’s a runbook with one task, titled “Say hello”, that a person or an agent may do.
A fuller runbook
Section titled “A fuller runbook”apiVersion: therunbook.app/v1 # optionalkind: Runbook # optionalmetadata: id: post-deploy title: Post-deploy verification owners: [team:oncall]spec: execution: title: "Verify ${{ inputs.service }}" timeout: 2h inputs: service: { type: enum, options: [api, web], required: true } fields: severity: { type: enum, options: [none, minor, major], default: none, indexed: true } vars: { result: undetermined } defaults: { actor: agent, timeout: 15m } steps: - id: check check: true instructions: Check ${{ inputs.service }}'s error rate. outputs: status_code: { type: integer, required: true } - id: record if: "${{ steps.check.verdict == 'fail' }}" set: { fields: { severity: major }, vars: { result: failed } } outputs: result: "${{ vars.result }}"| Part | What it holds | Read more |
|---|---|---|
metadata |
The ID, a title, tags and owners | Keys |
spec.execution |
Each run’s title, tags, timeout and concurrency limit | Keys |
spec.inputs, fields, vars, outputs |
The run’s data | Data |
spec.defaults |
What every task inherits | Keys |
spec.skills, spec.agents |
Skills steps use, parameters for agent launchers | Skills |
spec.triggers |
Schedules and webhook triggers that start runs | Keys |
spec.steps, spec.finally |
The procedure | Control flow |
spec.report |
A Markdown summary rendered when the run ends | Keys |
Keys starting with x- are allowed anywhere: they’re kept verbatim and
never executed, so you can carry your own metadata. Any other key the
language doesn’t have is refused (spec.unknown_key): a typo never silently
does nothing.
Kinds of steps
Section titled “Kinds of steps”A step’s kind comes from the key it carries. A step without one of these keys is a task.
| Kind | Key | What it does |
|---|---|---|
| Task | instructions (or nothing) |
Work for a person or an agent |
| Check | check: true |
A task that also records a verdict: pass, warn or fail |
| Approval | approval |
A decision between options, by named approvers |
| Wait | wait |
Waits for a duration, a time or a signal |
| Set | set |
Changes variables and fields |
| End | end |
Ends the run early |
| Call | call |
Runs another runbook as a child run |
| Group | steps |
Steps in order, with catch and finally |
| Parallel | parallel |
Branches at the same time |
| For each | foreach |
The same steps once per item |
| Loop | loop |
Steps repeated until a condition holds |
| Switch | switch |
The first matching case’s steps |
From file to run
Section titled “From file to run”- spec validateWriteYAML in your editor, the web app or git
- push --draftDraftSaved to a project, checked on every save
- publishPublishNames resolve, policy checked, version pinned
- run startRunEach run uses one published version
- Validate offline.
runbook spec validate my-runbook.yamlparses and compiles the whole runbook: keys, types, expressions, limits. It printsokand the worst-case number of step runs, or each diagnostic with its path and code. - Save a draft (
runbook push), from the CLI, the web app’s editor, MCP or a Git repository. - Publish. Publishing compiles again against your server: teams, people, skills and called runbooks resolve, and the publication rules for approvals and destructive steps are checked. Each publish is a new numbered version, and a run keeps the version it started with.
$ runbook spec validate hello.yamlok (worst case 1 step runs)
$ runbook spec validate broken.yaml/spec/steps/0/actr: spec.unknown_key: spec.unknown_keyEach line is the path into the document (a JSON pointer), the code, and a
message (the code again when there’s nothing more specific to say). The exit
status is 0 when valid and 2 when not; --json prints the report as
JSON.
Durations and recipients
Section titled “Durations and recipients”Two value formats appear throughout:
- Durations are digits and a unit, combinable:
500ms,90s,15m,2h,1d,1h30m. - Recipients (owners, assignees, escalation) are
team:<slug>,user:<name>, or a bare user name.