Your first runbook, agent run and approval
This walkthrough uses the CLI against a server you started in a
quick start. Install the CLI
and sign in first with runbook login https://your-server.
Write it
Section titled “Write it”Only IDs are required. Save this as hello.yaml:
metadata: { id: hello }spec: inputs: service: { type: string, required: true } steps: - id: check_health actor: agent instructions: Call /healthz on ${{ inputs.service }}; pass on 200. - id: go_no_go approval: prompt: Keep ${{ inputs.service }} running? options: [keep, rollback] approvers: { teams: [approvers] }Check it offline:
runbook spec validate hello.yamlPublish it
Section titled “Publish it”An approval names who may decide it, and names resolve against your server
when you publish. Make the approvers team and add yourself, with the
user_id that bootstrap printed:
runbook team create --slug approvers --title Approversrunbook team member add approvers usr_REPLACE_WITH_YOUR_USER_IDThe first runbook of a project is pushed with --draft, then published:
runbook push hello.yaml --project default --draftrunbook publish hello --project defaultStart a run
Section titled “Start a run”EXE=$(runbook run start hello --project default --input service=api --json | jq -r .id)Work the agent’s step
Section titled “Work the agent’s step”Give an agent an execution-scoped credential, never a person’s token. A service token mints one for a run:
runbook run token "$EXE" --session agent-1Then the agent loop: ask what’s next, claim the step, read it, report it.
runbook step next "$EXE"runbook step claim "$SR" --session agent-1 --agent-name my-agent --model manualrunbook step get "$SR"runbook step report "$SR" --status succeeded --verdict pass --output status_code=200step next prints next: claim_ready_work with the ready steps and their
step run IDs (sr_…), or next: wait when nothing is ready for this actor.
An execution credential can read only the step it has claimed.
To run a real command under the step’s lease, use step exec; it streams the
output into the step’s log with secrets redacted and reports from the exit
code:
runbook step exec "$SR" -- ./scripts/smoke-test.sh --env prodDecide the approval
Section titled “Decide the approval”Approvals aren’t in the agent’s brief; a person decides them. Find the step run in the run report and decide:
runbook run report "$EXE" --format mdrunbook step decide "$SR" --option keep --comment "Healthy"Check the outcome
Section titled “Check the outcome”runbook run get "$EXE" --waitrunbook run report "$EXE" --format mdThe run report reads like a document: who did each step, their outputs, logs and evidence. Export it as Markdown, JSON, JUnit or PDF.