CLI reference
Every command and flag of the runbook CLI, generated from its own
definitions. Run runbook <command> --help for the same text in a
terminal.
Global options
Section titled “Global options”These work with every command.
--host <HOST>: Runbook server host URL--context <CONTEXT>: Configured context name to use
Commands
Section titled “Commands”context: Manage CLI contextsspec: Manage and validate runbook specsrun: Manage and inspect executionsstep: Agent loop: next, claim, heartbeat, log, reportwhoami: Show which credentials and host the CLI usesme: Current user tasks and inboxuser: Pilot administration: usersproject: Pilot administration: projects and project rolesteam: Pilot administration: teams and team memberslogin: Store a personal access token for the current hostlogout: Forget the stored token for the current hosttoken: Create, list and revoke personal access tokensapps: List and disconnect the OAuth apps (MCP clients) you connectedwebhook: Manage webhook subscriptions and deliveriesmemory: Search, save and manage runbook memoryarchive: List and download runbook execution archiveslist: List a project’s runbooksget: Show a runbook, its latest published version, input schema and step outlinepull: Write a runbook’s draft source to a file or stdoutpush: Create or update a runbook from a file and publish it (–draft saves only)publish: Publish a runbook’s current draftdiff: Compare a local spec file with the published runbook, or two published versionsmcp: Model Context Protocol serverskill: Manage and install agent skillssync: Sync a repository folder of runbooks with a project (push from CI, pull to start)version: Show this CLI’s release and the server’s release and schema
runbook context
Section titled “runbook context”Manage CLI contexts
runbook context <COMMAND>Commands
add: Add or update a contextuse: Switch current contextlist: List all contextsremove: Remove a context and forget its login
runbook context add
Section titled “runbook context add”Add or update a context
runbook context add <NAME> [OPTIONS]Arguments
NAME: Context name Required.
Options
--host <HOST>: Runbook server host URL Required.--default-project <PROJECT>: Project (ID or slug) commands use in this context when they name none
runbook context use
Section titled “runbook context use”Switch current context
runbook context use <NAME>Arguments
NAME: Context name Required.
runbook context list
Section titled “runbook context list”List all contexts
runbook context list [OPTIONS]Options
--json: Output as JSON
runbook context remove
Section titled “runbook context remove”Remove a context and forget its login
runbook context remove <NAME>Arguments
NAME: Context name Required.
runbook spec
Section titled “runbook spec”Manage and validate runbook specs
runbook spec <COMMAND>Commands
validate: Validate a runbook spec offline
runbook spec validate
Section titled “runbook spec validate”Validate a runbook spec offline
runbook spec validate <FILE> [OPTIONS]Arguments
FILE: Path to the runbook spec file Required.
Options
--json: Output validation report as JSON
runbook run
Section titled “runbook run”Manage and inspect executions
runbook run <COMMAND>Commands
start: Start an executionget: Get an execution’s detailslist: List executionswatch: Watch execution events in real timesignal: Send a signal to an executionreport: View an execution reportcancel: Cancel an executionpause: Pause an executionresume: Resume an executionupdate: Update execution metadatarerun: Rerun an executionfields: Manage execution fieldstoken: Mint an execution access/refresh pair
runbook run start
Section titled “runbook run start”Start an execution
runbook run start <RUNBOOK> [OPTIONS]Arguments
RUNBOOK: Runbook reference (<runbook>[@<n|rbv_id>]) Required.
Options
--project <PROJECT>: Project ID or slug Required. Environment:RUNBOOK_PROJECT.--input <INPUTS>: Input parameter (key=val) Repeatable.--field <FIELDS>: Field parameter (key=val) Repeatable.--tag <TAGS>: Execution tag Repeatable.--title <TITLE>: Execution title--idempotency-key <IDEMPOTENCY_KEY>: Idempotency key--wait: Poll until the execution is terminal; exit 3 if it failed or was cancelled--follow: Stream the execution’s events until it ends (implies –wait)--json: Output response as JSON
runbook run get
Section titled “runbook run get”Get an execution’s details
runbook run get <EXECUTION_ID> [OPTIONS]Arguments
EXECUTION_ID: Execution ID Required.
Options
--wait: Poll until the execution is terminal; exit 3 if it failed--fail-on <FAIL_ON>: Exit 1 if final status matches (e.g. failed, cancelled) Repeatable.--json: Output response as JSON
runbook run list
Section titled “runbook run list”List executions
runbook run list [OPTIONS]Options
--project <PROJECT>: Project ID or slug Required. Environment:RUNBOOK_PROJECT.--status <STATUS>: Filter by status (comma list) Repeatable.--tag <TAGS>: Filter by tag Repeatable.--runbook <RUNBOOK>: Filter by runbook (<slug|rb_id>)--field <FIELDS>: Filter by field (key=val) Repeatable.--limit <LIMIT>: Page limit (1-100)--cursor <CURSOR>: Pagination cursor--all: Page through all executions--json: Output response as JSON--jsonl: Stream JSON objects one per line
runbook run watch
Section titled “runbook run watch”Watch execution events in real time
runbook run watch <EXECUTION_ID> [OPTIONS]Arguments
EXECUTION_ID: Execution ID Required.
Options
--after <AFTER>: Resume after sequence number--json: Output raw event data as JSON--jsonl: Stream JSON objects one per line
runbook run signal
Section titled “runbook run signal”Send a signal to an execution
runbook run signal <EXECUTION_ID> <NAME> [OPTIONS]Arguments
EXECUTION_ID: Execution ID Required.NAME: Signal name Required.
Options
--payload <PAYLOAD>: Payload parameter (key=val) Repeatable.--idempotency-key <IDEMPOTENCY_KEY>: Idempotency key--json: Output response as JSON
runbook run report
Section titled “runbook run report”View an execution report
runbook run report <EXECUTION_ID> [OPTIONS]Arguments
EXECUTION_ID: Execution ID Required.
Options
--format <FORMAT>: Export format: md (Markdown text), json, junit (JUnit XML) or pdf One ofmd,json,junit,pdf.--out <FILE>: Write the report to FILE instead of stdout (a PDF needs this unless stdout is redirected)--json: Output response as JSON
runbook run cancel
Section titled “runbook run cancel”Cancel an execution
runbook run cancel <EXECUTION_ID> [OPTIONS]Arguments
EXECUTION_ID: Execution ID Required.
Options
--idempotency-key <IDEMPOTENCY_KEY>: Idempotency key--json: Output response as JSON
runbook run pause
Section titled “runbook run pause”Pause an execution
runbook run pause <EXECUTION_ID> [OPTIONS]Arguments
EXECUTION_ID: Execution ID Required.
Options
--idempotency-key <IDEMPOTENCY_KEY>: Idempotency key--json: Output response as JSON
runbook run resume
Section titled “runbook run resume”Resume an execution
runbook run resume <EXECUTION_ID> [OPTIONS]Arguments
EXECUTION_ID: Execution ID Required.
Options
--idempotency-key <IDEMPOTENCY_KEY>: Idempotency key--json: Output response as JSON
runbook run update
Section titled “runbook run update”Update execution metadata
runbook run update <EXECUTION_ID> [OPTIONS]Arguments
EXECUTION_ID: Execution ID Required.
Options
--title <TITLE>: Execution title--tag <TAGS>: Execution tag Repeatable.--field <FIELDS>: Field parameter (key=val) Repeatable.--idempotency-key <IDEMPOTENCY_KEY>: Idempotency key--json: Output response as JSON
runbook run rerun
Section titled “runbook run rerun”Rerun an execution
runbook run rerun <EXECUTION_ID> [OPTIONS]Arguments
EXECUTION_ID: Execution ID Required.
Options
--idempotency-key <IDEMPOTENCY_KEY>: Idempotency key--json: Output response as JSON
runbook run fields
Section titled “runbook run fields”Manage execution fields
runbook run fields <COMMAND>Commands
set: Set execution fields
runbook run fields set
Section titled “runbook run fields set”Set execution fields
runbook run fields set <EXECUTION_ID> <FIELDS...> [OPTIONS]Arguments
EXECUTION_ID: Execution ID Required.FIELDS...: Field parameter (key=val) Required.
Options
--idempotency-key <IDEMPOTENCY_KEY>: Idempotency key--json: Output response as JSON
runbook run token
Section titled “runbook run token”Mint an execution access/refresh pair
runbook run token <EXECUTION_ID> [OPTIONS]Arguments
EXECUTION_ID: Execution ID Required.
Options
--session <SESSION>: Session ID recorded with the credential family--idempotency-key <IDEMPOTENCY_KEY>: Idempotency key--json: Print the pair once as JSON instead of storing it (the caller installs it)
runbook step
Section titled “runbook step”Agent loop: next, claim, heartbeat, log, report
runbook step <COMMAND>Commands
next: Show the resume brief: completed work and ready stepsget: Read the step you claimed: instructions, checklist and pinned skill (claim first)skill-file: Read one file of the claimed step’s pinned skillclaim: Claim a ready step run (then read it withstep get)heartbeat: Extend the current claim’s leaselog: Append stdin lines to the step’s logreport: Report the step’s resultevidence: Upload an evidence file for the step runchecklist: Set the step’s checklist (ticked items complete, the rest open)decide: Decide an approvalrelease: Release a claim (or, with –reason, an admin release)request-human: Hand the step to a personexec: Run a local command as the claimed step’s work: stream its output as logs, heartbeat, and report by exit code
runbook step next
Section titled “runbook step next”Show the resume brief: completed work and ready steps
runbook step next <EXECUTION_ID> [OPTIONS]Arguments
EXECUTION_ID: Execution ID Required.
Options
--json: Output response as JSON
runbook step get
Section titled “runbook step get”Read the step you claimed: instructions, checklist and pinned skill (claim first)
runbook step get <STEP_RUN_ID> [OPTIONS]Arguments
STEP_RUN_ID: Step run ID Required.
Options
--json: Output response as JSON
runbook step skill-file
Section titled “runbook step skill-file”Read one file of the claimed step’s pinned skill
runbook step skill-file <STEP_RUN_ID> <PATH> [OPTIONS]Arguments
STEP_RUN_ID: Step run ID Required.PATH: Relative path in the pinned skill Required.
Options
--skill <SKILL>: Skill alias or 64-char hex hash when the step has multiple skills--json: Output response as JSON (base64 content)
runbook step claim
Section titled “runbook step claim”Claim a ready step run (then read it with step get)
runbook step claim <STEP_RUN_ID> [OPTIONS]Arguments
STEP_RUN_ID: Step run ID Required.
Options
--session <SESSION>: Session ID of this actor session Required.--agent-name <AGENT_NAME>: Agent name (declares an agent actor)--model <MODEL>: Model name--take-over: Take over a ready agent step as a person (never a live agent claim)--idempotency-key <IDEMPOTENCY_KEY>: Idempotency key--json: Output response as JSON
runbook step heartbeat
Section titled “runbook step heartbeat”Extend the current claim’s lease
runbook step heartbeat <STEP_RUN_ID> [OPTIONS]Arguments
STEP_RUN_ID: Step run ID Required.
Options
--claim <CLAIM>: Claim reference <claim_id>:<generation> (default: stored)--idempotency-key <IDEMPOTENCY_KEY>: Idempotency key--json: Output response as JSON
runbook step log
Section titled “runbook step log”Append stdin lines to the step’s log
runbook step log <STEP_RUN_ID> [OPTIONS]Arguments
STEP_RUN_ID: Step run ID Required.
Options
--claim <CLAIM>: Claim reference <claim_id>:<generation> (default: stored)--idempotency-key <IDEMPOTENCY_KEY>: Idempotency key--json: Output response as JSON
runbook step report
Section titled “runbook step report”Report the step’s result
runbook step report <STEP_RUN_ID> [OPTIONS]Arguments
STEP_RUN_ID: Step run ID Required.
Options
--status <STATUS>: Whether the work was performed Required. One ofsucceeded,failed.--verdict <VERDICT>: Check verdict, independent of status One ofpass,warn,fail.--output <OUTPUTS>: Output value (key=val) Repeatable.--summary <SUMMARY>: Summary--evidence <EVIDENCE>: Evidence URL, ID, or local file path Repeatable.--resize: Downscale image if it exceeds server limits--log-file <LOG_FILE>: File whose lines are sent as step logs (through the logs route, before the report)--claim <CLAIM>: Claim reference <claim_id>:<generation> (default: stored)--idempotency-key <IDEMPOTENCY_KEY>: Idempotency key--json: Output response as JSON
runbook step evidence
Section titled “runbook step evidence”Upload an evidence file for the step run
runbook step evidence <STEP_RUN_ID> <FILE> [OPTIONS]Arguments
STEP_RUN_ID: Step run ID Required.FILE: Evidence file to upload Required.
Options
--resize: Downscale image if it exceeds server limits--claim <CLAIM>: Claim reference <claim_id>:<generation> (default: stored)--idempotency-key <IDEMPOTENCY_KEY>: Idempotency key--json: Output response as JSON
runbook step checklist
Section titled “runbook step checklist”Set the step’s checklist (ticked items complete, the rest open)
runbook step checklist <STEP_RUN_ID> [OPTIONS]Arguments
STEP_RUN_ID: Step run ID Required.
Options
--tick <TICKS>: Completed item title (repeat for each) Repeatable.--claim <CLAIM>: Claim reference <claim_id>:<generation> (default: stored)--idempotency-key <IDEMPOTENCY_KEY>: Idempotency key--json: Output response as JSON
runbook step decide
Section titled “runbook step decide”Decide an approval
runbook step decide <STEP_RUN_ID> [OPTIONS]Arguments
STEP_RUN_ID: Step run ID of the approval Required.
Options
--option <OPTION>: Option ID Required.--comment <COMMENT>: Comment--session <SESSION>: Session ID (required for agents)--agent-name <AGENT_NAME>: Agent name--model <MODEL>: Model name--idempotency-key <IDEMPOTENCY_KEY>: Idempotency key--json: Output response as JSON
runbook step release
Section titled “runbook step release”Release a claim (or, with –reason, an admin release)
runbook step release <STEP_RUN_ID> [OPTIONS]Arguments
STEP_RUN_ID: Step run ID Required.
Options
--reason <REASON>: Admin release reason (project admin; no claim)--claim <CLAIM>: Claim reference <claim_id>:<generation> (default: stored)--idempotency-key <IDEMPOTENCY_KEY>: Idempotency key--json: Output response as JSON
runbook step request-human
Section titled “runbook step request-human”Hand the step to a person
runbook step request-human <STEP_RUN_ID> [OPTIONS]Arguments
STEP_RUN_ID: Step run ID Required.
Options
--reason <REASON>: Why a person is needed Required.--question <QUESTION>: The question for the person Required.--claim <CLAIM>: Claim reference <claim_id>:<generation> (default: stored)--idempotency-key <IDEMPOTENCY_KEY>: Idempotency key--json: Output response as JSON
runbook step exec
Section titled “runbook step exec”Run a local command as the claimed step’s work: stream its output as logs, heartbeat, and report by exit code
runbook step exec <STEP_RUN_ID> <COMMAND...> [OPTIONS]Arguments
STEP_RUN_ID: Step run ID (claim it first) Required.COMMAND...: The command and its arguments, after--Required.
Options
--claim <CLAIM>: Claim reference <claim_id>:<generation> (default: stored)--idempotency-key <IDEMPOTENCY_KEY>: Idempotency key--json: Output response as JSON
runbook whoami
Section titled “runbook whoami”Show which credentials and host the CLI uses
runbook whoami [OPTIONS]Options
--json: Output as JSON
runbook me
Section titled “runbook me”Current user tasks and inbox
runbook me <COMMAND>Commands
tasks: List open tasks and approvals for the current user
runbook me tasks
Section titled “runbook me tasks”List open tasks and approvals for the current user
runbook me tasks [OPTIONS]Options
--kind <KIND>: Filter by item kind: approval, human_task--limit <LIMIT>: Page limit (1-100)--cursor <CURSOR>: Pagination cursor--json: Output response as JSON
runbook user
Section titled “runbook user”Pilot administration: users
runbook user <COMMAND>Commands
create: Create a user in the organizationdeactivate: Deactivate a userlist: List users in the organization
runbook user create
Section titled “runbook user create”Create a user in the organization
runbook user create [OPTIONS]Options
--name <NAME>: Display name Required.--org <ORG>: Organization ID (default: the only one visible)--idempotency-key <IDEMPOTENCY_KEY>: Idempotency key--json: Output response as JSON
runbook user deactivate
Section titled “runbook user deactivate”Deactivate a user
runbook user deactivate <USER> [OPTIONS]Arguments
USER: User ID (usr_…) Required.
Options
--org <ORG>: Organization ID (default: the only one visible)--idempotency-key <IDEMPOTENCY_KEY>: Idempotency key--json: Output response as JSON
runbook user list
Section titled “runbook user list”List users in the organization
runbook user list [OPTIONS]Options
--org <ORG>: Organization ID (default: the only one visible)--json: Output response as JSON
runbook project
Section titled “runbook project”Pilot administration: projects and project roles
runbook project <COMMAND>Commands
runbook project create
Section titled “runbook project create”Create a project
runbook project create [OPTIONS]Options
--slug <SLUG>: Slug (lowercase kebab-case) Required.--title <TITLE>: Title Required.--org <ORG>: Organization ID (default: the only one visible)--idempotency-key <IDEMPOTENCY_KEY>: Idempotency key--json: Output response as JSON
runbook project member
Section titled “runbook project member”Grant or revoke project roles
runbook project member <COMMAND>Commands
runbook project member add
Section titled “runbook project member add”Grant a user a project role
runbook project member add <PROJECT> <USER> [OPTIONS]Arguments
PROJECT: Project ID or slug Required.USER: User ID (usr_…) Required.
Options
--role <ROLE>: Project role One ofviewer,operator,editor,admin. Defaultviewer.--org <ORG>: Organization ID (default: the only one visible)--idempotency-key <IDEMPOTENCY_KEY>: Idempotency key--json: Output response as JSON
runbook project member remove
Section titled “runbook project member remove”Revoke a user’s project role
runbook project member remove <GROUP> <USER> [OPTIONS]Arguments
GROUP: Project or team ID or slug Required.USER: User ID (usr_…) Required.
Options
--org <ORG>: Organization ID (default: the only one visible)--json: Output response as JSON
runbook project member list
Section titled “runbook project member list”List project members
runbook project member list <PROJECT> [OPTIONS]Arguments
PROJECT: Project ID or slug Required.
Options
--org <ORG>: Organization ID (default: the only one visible)--json: Output response as JSON
runbook team
Section titled “runbook team”Pilot administration: teams and team members
runbook team <COMMAND>Commands
runbook team create
Section titled “runbook team create”Create a team
runbook team create [OPTIONS]Options
--slug <SLUG>: Slug (lowercase kebab-case) Required.--title <TITLE>: Title Required.--org <ORG>: Organization ID (default: the only one visible)--idempotency-key <IDEMPOTENCY_KEY>: Idempotency key--json: Output response as JSON
runbook team list
Section titled “runbook team list”List teams in the organization
runbook team list [OPTIONS]Options
--org <ORG>: Organization ID (default: the only one visible)--json: Output response as JSON
runbook team member
Section titled “runbook team member”Add or remove team members
runbook team member <COMMAND>Commands
runbook team member add
Section titled “runbook team member add”Add a user to a team
runbook team member add <TEAM> <USER> [OPTIONS]Arguments
TEAM: Team ID or slug Required.USER: User ID (usr_…) Required.
Options
--org <ORG>: Organization ID (default: the only one visible)--idempotency-key <IDEMPOTENCY_KEY>: Idempotency key--json: Output response as JSON
runbook team member remove
Section titled “runbook team member remove”Remove a user from a team
runbook team member remove <GROUP> <USER> [OPTIONS]Arguments
GROUP: Project or team ID or slug Required.USER: User ID (usr_…) Required.
Options
--org <ORG>: Organization ID (default: the only one visible)--json: Output response as JSON
runbook login
Section titled “runbook login”Store a personal access token for the current host
runbook login [HOST] [OPTIONS]Arguments
HOST: Host URL to log in to
Options
--token-stdin: Read a personal access token from stdin--migrate-to-keychain: Move every login stored in the 0600 file into the OS keychain--no-browser: Do not attempt to open a browser--scope <SCOPE>: Ask for exactly this scope (repeatable) instead of the default set Repeatable.--admin: Also ask for the admin scopes (tokens:manage, project:admin, webhooks:manage, executions:admin)--json: Output as JSON
runbook logout
Section titled “runbook logout”Forget the stored token for the current host
runbook logout [OPTIONS]Options
--json: Output as JSON
runbook token
Section titled “runbook token”Create, list and revoke personal access tokens
runbook token <COMMAND>Commands
create: Create a personal access token (the secret is shown once)list: List your tokensrevoke: Revoke a token
runbook token create
Section titled “runbook token create”Create a personal access token (the secret is shown once)
runbook token create [OPTIONS]Options
--name <NAME>: Token name--scope <SCOPES>: Narrow to a scope (repeat for each) Repeatable.--project <PROJECTS>: Narrow to a project ID or slug (repeat) Repeatable.--expires-in <EXPIRES>: Lifetime: <n>d or <n>h, at most 365d--kind <KIND>: Token kind: personal or service (default personal)--role <ROLE>: Role for service token: viewer, operator, editor, admin (default operator)--agent: Agent-kind token (D26): agent provenance with you as sponsor; never casts human approvals--user <USER>: Must be you: the server never issues tokens for another user (usr_…)--idempotency-key <IDEMPOTENCY_KEY>: Idempotency key--json: Output the response (with the secret) as JSON
runbook token list
Section titled “runbook token list”List your tokens
runbook token list [OPTIONS]Options
--json: Output response as JSON
runbook token revoke
Section titled “runbook token revoke”Revoke a token
runbook token revoke <TOKEN> [OPTIONS]Arguments
TOKEN: Token ID (tok_…) Required.
Options
--json: Output response as JSON
runbook apps
Section titled “runbook apps”List and disconnect the OAuth apps (MCP clients) you connected
runbook apps <COMMAND>Commands
list: List the OAuth apps (MCP clients) you connectedrevoke: Disconnect an OAuth app: its tokens stop working now
runbook apps list
Section titled “runbook apps list”List the OAuth apps (MCP clients) you connected
runbook apps list [OPTIONS]Options
--json: Output response as JSON
runbook apps revoke
Section titled “runbook apps revoke”Disconnect an OAuth app: its tokens stop working now
runbook apps revoke <CLIENT> [OPTIONS]Arguments
CLIENT: Client ID (fromrunbook apps list) Required.
Options
--json: Output response as JSON
runbook webhook
Section titled “runbook webhook”Manage webhook subscriptions and deliveries
runbook webhook <COMMAND>Commands
list: List a project’s webhook subscriptionscreate: Create a subscription (prints its signing secret once)update: Update a subscription; omitted options are unchangeddelete: Delete a subscription and its delivery logtest: Send a webhook.test event to a subscriptiondeliveries: Show a subscription’s delivery logredeliver: Send a delivery’s event again under a new delivery IDrotate-secret: Rotate the signing secret (prints the new secret once)
runbook webhook list
Section titled “runbook webhook list”List a project’s webhook subscriptions
runbook webhook list [OPTIONS]Options
--project <PROJECT>: Project ID or slug Required. Environment:RUNBOOK_PROJECT.--json: Output response as JSON
runbook webhook create
Section titled “runbook webhook create”Create a subscription (prints its signing secret once)
runbook webhook create [OPTIONS]Options
--project <PROJECT>: Project ID or slug Required. Environment:RUNBOOK_PROJECT.--url <URL>: HTTPS endpoint Required.--event <EVENTS>: Event type, or * for all (repeat for each) Required. Repeatable.--name <NAME>: Subscription name (default: the URL)--runbook <RUNBOOKS>: Only events of this runbook (rb_…; repeat) Repeatable.--tag <TAGS>: Only executions with this tag (repeat) Repeatable.--disabled: Create the subscription disabled--idempotency-key <IDEMPOTENCY_KEY>: Idempotency key--json: Output the response (with the secret) as JSON
runbook webhook update
Section titled “runbook webhook update”Update a subscription; omitted options are unchanged
runbook webhook update <ID> [OPTIONS]Arguments
ID: Webhook ID (whk_…) Required.
Options
--project <PROJECT>: Project ID or slug Required. Environment:RUNBOOK_PROJECT.--name <NAME>: New name--url <URL>: New HTTPS endpoint--event <EVENTS>: Replace the event types (repeat) Repeatable.--runbook <RUNBOOKS>: Replace the runbook filter (rb_…; repeat) Repeatable.--clear-runbooks: Remove the runbook filter--tag <TAGS>: Replace the tag filter (repeat) Repeatable.--clear-tags: Remove the tag filter--enable: Enable (and reset delivery health)--disable: Disable--json: Output response as JSON
runbook webhook delete
Section titled “runbook webhook delete”Delete a subscription and its delivery log
runbook webhook delete <ID> [OPTIONS]Arguments
ID: Webhook ID (whk_…) Required.
Options
--project <PROJECT>: Project ID or slug Required. Environment:RUNBOOK_PROJECT.--json: Output response as JSON
runbook webhook test
Section titled “runbook webhook test”Send a webhook.test event to a subscription
runbook webhook test <ID> [OPTIONS]Arguments
ID: Webhook ID (whk_…) Required.
Options
--project <PROJECT>: Project ID or slug Required. Environment:RUNBOOK_PROJECT.--idempotency-key <IDEMPOTENCY_KEY>: Idempotency key--json: Output response as JSON
runbook webhook deliveries
Section titled “runbook webhook deliveries”Show a subscription’s delivery log
runbook webhook deliveries <ID> [OPTIONS]Arguments
ID: Webhook ID (whk_…) Required.
Options
--project <PROJECT>: Project ID or slug Required. Environment:RUNBOOK_PROJECT.--limit <LIMIT>: Page limit (1-100)--cursor <CURSOR>: Pagination cursor--json: Output response as JSON
runbook webhook redeliver
Section titled “runbook webhook redeliver”Send a delivery’s event again under a new delivery ID
runbook webhook redeliver <DELIVERY> [OPTIONS]Arguments
DELIVERY: Delivery ID (whd_…) Required.
Options
--webhook <WEBHOOK>: Webhook ID the delivery belongs to (whk_…) Required.--project <PROJECT>: Project ID or slug Required. Environment:RUNBOOK_PROJECT.--idempotency-key <IDEMPOTENCY_KEY>: Idempotency key--json: Output response as JSON
runbook webhook rotate-secret
Section titled “runbook webhook rotate-secret”Rotate the signing secret (prints the new secret once)
runbook webhook rotate-secret <ID> [OPTIONS]Arguments
ID: Webhook ID (whk_…) Required.
Options
--project <PROJECT>: Project ID or slug Required. Environment:RUNBOOK_PROJECT.--idempotency-key <IDEMPOTENCY_KEY>: Idempotency key--json: Output response as JSON
runbook memory
Section titled “runbook memory”Search, save and manage runbook memory
runbook memory <COMMAND>Commands
search: Search a runbook’s active memorysave: Save a durable fact for future runs: live at once, or a proposal with –proposeedit: Edit a memory entry at the revision you read (agents and people)history: List a memory entry’s revisions and who wrote each (people only)revert: Restore a prior revision’s content as a new revision; unarchives (people only)lock: Lock a memory entry so agents cannot edit it (people only)unlock: Unlock a memory entry (people only)list: List memory entries (use –proposed for proposals)accept: Accept a proposed memory entry (people only)reject: Reject a proposed memory entry, or every proposal of a runbook (people only)archive: Archive a memory entry (people only)
runbook memory search
Section titled “runbook memory search”Search a runbook’s active memory
runbook memory search <RUNBOOK> [QUERY] [OPTIONS]Arguments
RUNBOOK: Runbook ID or slug Required.QUERY: Words that must all appear in the title or body
Options
--project <PROJECT>: Project ID or slug (required when <runbook> is a slug) Environment:RUNBOOK_PROJECT.--step <STEP>: Step ID or step path--tag <TAGS>: Tag (repeat for multiple tags) Repeatable.--json: Output response as JSON--limit <LIMIT>: Page limit (1-100)--cursor <CURSOR>: Pagination cursor
runbook memory save
Section titled “runbook memory save”Save a durable fact for future runs: live at once, or a proposal with –propose
runbook memory save [RUNBOOK] [OPTIONS]Arguments
RUNBOOK: Runbook ID or slug
Options
--runbook <RUNBOOK_FLAG>: Runbook ID or slug--project <PROJECT>: Project ID or slug Environment:RUNBOOK_PROJECT.--title <TITLE>: Short title Required.--body-file <BODY_FILE>: Path to markdown body file, or ‘-’ for stdin Required.--step <STEP>: Step ID or step path--tag <TAGS>: Tag (repeat for multiple tags) Repeatable.--step-run <STEP_RUN>: The step run you claim: save with that run’s stored execution credentials--idempotency-key <IDEMPOTENCY_KEY>: Idempotency key--propose: Save a proposal a person reviews instead of a live entry--json: Output response as JSON
runbook memory edit
Section titled “runbook memory edit”Edit a memory entry at the revision you read (agents and people)
runbook memory edit <MEM> [OPTIONS]Arguments
MEM: Memory ID (mem_…) Required.
Options
--revision <REVISION>: The revision you read; refused if it changed (412 memory.conflict) Required.--title <TITLE>: New title (default: keep)--body-file <BODY_FILE>: Path to the new markdown body, or ‘-’ for stdin (default: keep)--step <STEP>: New step ID or step path (default: keep)--tag <TAGS>: Tag (repeat; replaces every tag; default: keep) Repeatable.--step-run <STEP_RUN>: The step run you claim: edit with that run’s stored execution credentials--json: Output response as JSON
runbook memory history
Section titled “runbook memory history”List a memory entry’s revisions and who wrote each (people only)
runbook memory history <MEM> [OPTIONS]Arguments
MEM: Memory ID (mem_…) Required.
Options
--limit <LIMIT>: Page limit (1-100)--cursor <CURSOR>: Pagination cursor (next:of the last page)--json: Output response as JSON
runbook memory revert
Section titled “runbook memory revert”Restore a prior revision’s content as a new revision; unarchives (people only)
runbook memory revert <MEM> [OPTIONS]Arguments
MEM: Memory ID (mem_…) Required.
Options
--to <TO>: The revision whose content to restore Required.--json: Output response as JSON
runbook memory lock
Section titled “runbook memory lock”Lock a memory entry so agents cannot edit it (people only)
runbook memory lock <MEM> [OPTIONS]Arguments
MEM: Memory ID (mem_…) Required.
Options
--json: Output response as JSON
runbook memory unlock
Section titled “runbook memory unlock”Unlock a memory entry (people only)
runbook memory unlock <MEM> [OPTIONS]Arguments
MEM: Memory ID (mem_…) Required.
Options
--json: Output response as JSON
runbook memory list
Section titled “runbook memory list”List memory entries (use –proposed for proposals)
runbook memory list [RUNBOOK] [OPTIONS]Arguments
RUNBOOK: Runbook ID or slug
Options
--runbook <RUNBOOK_FLAG>: Runbook ID or slug--project <PROJECT>: Project ID or slug Environment:RUNBOOK_PROJECT.--proposed: List proposed entries--status <STATUS>: Filter by status--json: Output response as JSON--limit <LIMIT>: Page limit (1-100)--cursor <CURSOR>: Pagination cursor
runbook memory accept
Section titled “runbook memory accept”Accept a proposed memory entry (people only)
runbook memory accept <MEM> [OPTIONS]Arguments
MEM: Memory ID (mem_…) Required.
Options
--revision <REVISION>: The revision you reviewed (frommemory list --proposed); refused if it changed Required.--json: Output response as JSON
runbook memory reject
Section titled “runbook memory reject”Reject a proposed memory entry, or every proposal of a runbook (people only)
runbook memory reject [MEM] [OPTIONS]Arguments
MEM: Memory ID (mem_…)
Options
--revision <REVISION>: The revision you reviewed; refused if it changed--all-proposed <RUNBOOK>: Reject every pending proposal of this runbook (ID or slug)--project <PROJECT>: Project ID or slug (required when RUNBOOK is a slug) Environment:RUNBOOK_PROJECT.--json: Output response as JSON
runbook memory archive
Section titled “runbook memory archive”Archive a memory entry (people only)
runbook memory archive <MEM> [OPTIONS]Arguments
MEM: Memory ID (mem_…) Required.
Options
--json: Output response as JSON
runbook archive
Section titled “runbook archive”List and download runbook execution archives
runbook archive <COMMAND>Commands
runbook archive list
Section titled “runbook archive list”List a runbook’s daily archive files
runbook archive list <RUNBOOK> [OPTIONS]Arguments
RUNBOOK: Runbook ID or slug Required.
Options
--project <PROJECT>: Project ID or slug (required when <runbook> is a slug) Environment:RUNBOOK_PROJECT.--from <FROM>: First UTC day, inclusive (YYYY-MM-DD)--to <TO>: Last UTC day, inclusive (YYYY-MM-DD)--json: Output response as JSON
runbook archive download
Section titled “runbook archive download”Download daily archive files or range bundle
runbook archive download <RUNBOOK> [OPTIONS]Arguments
RUNBOOK: Runbook ID or slug Required.
Options
--project <PROJECT>: Project ID or slug (required when <runbook> is a slug) Environment:RUNBOOK_PROJECT.--date <DATE>: Single UTC day to download (YYYY-MM-DD)--from <FROM>: First UTC day for bundle download, inclusive (YYYY-MM-DD)--to <TO>: Last UTC day for bundle download, inclusive (YYYY-MM-DD)--include-evidence: Include held evidence objects in archive bundle--out <OUT>: Output file path (default: sensible filename based on runbook and date range)
runbook list
Section titled “runbook list”List a project’s runbooks
runbook list [OPTIONS]Options
--project <PROJECT>: Project ID or slug Required. Environment:RUNBOOK_PROJECT.--limit <LIMIT>: Page limit (1-100)--cursor <CURSOR>: Pagination cursor--json: Output response as JSON
runbook get
Section titled “runbook get”Show a runbook, its latest published version, input schema and step outline
runbook get <RUNBOOK> [OPTIONS]Arguments
RUNBOOK: Runbook (rb_ ID, or slug with –project) Required.
Options
--project <PROJECT>: Project ID or slug (to resolve a slug) Environment:RUNBOOK_PROJECT.--json: Output response as JSON
runbook pull
Section titled “runbook pull”Write a runbook’s draft source to a file or stdout
runbook pull <RUNBOOK> [OPTIONS]Arguments
RUNBOOK: Runbook (rb_ ID, or slug with –project) Required.
Options
--project <PROJECT>: Project ID or slug (to resolve a slug) Environment:RUNBOOK_PROJECT.-o, --output <OUTPUT>: Write the source to this file--json: Output source and revision as JSON
runbook push
Section titled “runbook push”Create or update a runbook from a file and publish it (–draft saves only)
runbook push <FILE> [OPTIONS]Arguments
FILE: Runbook spec file (its metadata.id is the slug) Required.
Options
--project <PROJECT>: Project ID or slug Required. Environment:RUNBOOK_PROJECT.--draft: Save the draft without publishing--revision <REVISION>: Expected current draft revision (fail if it moved)--idempotency-key <IDEMPOTENCY_KEY>: Idempotency key--json: Output response as JSON
runbook publish
Section titled “runbook publish”Publish a runbook’s current draft
runbook publish <RUNBOOK> [OPTIONS]Arguments
RUNBOOK: Runbook (rb_ ID, or slug with –project) Required.
Options
--project <PROJECT>: Project ID or slug (to resolve a slug) Environment:RUNBOOK_PROJECT.--revision <REVISION>: Draft revision to publish (fail if the draft moved)--idempotency-key <IDEMPOTENCY_KEY>: Idempotency key--json: Output response as JSON
runbook diff
Section titled “runbook diff”Compare a local spec file with the published runbook, or two published versions
runbook diff <FILE|RUNBOOK@VERSION> [RUNBOOK@VERSION] [OPTIONS]Arguments
FILE|RUNBOOK@VERSION: A local spec file, or a published version <runbook>[@<n|rbv_id|latest>] Required.RUNBOOK@VERSION: The published version to compare with (default: the runbook’s latest)
Options
--project <PROJECT>: Project ID or slug (to resolve slugs and a file’s runbook)--text: Also show a unified diff of the two sources--json: Output as JSON
runbook mcp
Section titled “runbook mcp”Model Context Protocol server
runbook mcp <COMMAND>Commands
serve: Run a stdio MCP server using the current context
runbook mcp serve
Section titled “runbook mcp serve”Run a stdio MCP server using the current context
runbook mcp serverunbook skill
Section titled “runbook skill”Manage and install agent skills
runbook skill <COMMAND>Commands
list: List project skills and versions with runbook usagespush: Upload a skill folder (SKILL.md plus supporting files)pull: Download a skill folder from the projectinstall: Install skills into an agent’s skill directory
runbook skill list
Section titled “runbook skill list”List project skills and versions with runbook usages
runbook skill list [OPTIONS]Options
--project <PROJECT>: Project ID or slug (default: “default”) Environment:RUNBOOK_PROJECT.--limit <LIMIT>: Page limit (1-100)--cursor <CURSOR>: Pagination cursor--json: Output response as JSON
runbook skill push
Section titled “runbook skill push”Upload a skill folder (SKILL.md plus supporting files)
runbook skill push <DIR> [OPTIONS]Arguments
DIR: Path to the skill directory containing SKILL.md Required.
Options
--project <PROJECT>: Project ID or slug (default: “default”) Environment:RUNBOOK_PROJECT.--idempotency-key <IDEMPOTENCY_KEY>: Idempotency key--json: Output response as JSON
runbook skill pull
Section titled “runbook skill pull”Download a skill folder from the project
runbook skill pull <NAME> [OPTIONS]Arguments
NAME: Skill name, optionally with @<version|hash> (e.g. ‘foo’ or ‘foo@<hash>’) Required.
Options
--project <PROJECT>: Project ID or slug (default: “default”) Environment:RUNBOOK_PROJECT.--out <OUT>: Output directory (default: ./<name>)--force: Allow overwriting non-empty target directory--json: Output response as JSON
runbook skill install
Section titled “runbook skill install”Install skills into an agent’s skill directory
runbook skill install [OPTIONS]Options
--agent <AGENT>: Target agent: claude, codex, or cursor (default: every one of them set up in your home directory) One ofclaude,codex,cursor.--scope <SCOPE>: Installation scope: user or project One ofuser,project. Defaultuser.--project <PROJECT>: Project ID or slug (default: “default”) Environment:RUNBOOK_PROJECT.--skill <SKILL>: Specific skill name to install (default: all project skills)--therunbook: Install the bundled therunbook agent skill itself (embedded in binary)--force: Allow overwriting non-empty target directory--json: Output response as JSON
runbook sync
Section titled “runbook sync”Sync a repository folder of runbooks with a project (push from CI, pull to start)
runbook sync <COMMAND>Commands
push: Publish a folder of runbook sources to its project as one batch (from CI); any invalid file refuses the batchpull: Write each runbook’s latest published source to a folder (to start a repository from the app)
runbook sync push
Section titled “runbook sync push”Publish a folder of runbook sources to its project as one batch (from CI); any invalid file refuses the batch
runbook sync push <DIR> [OPTIONS]Arguments
DIR: Folder of <runbook>.yaml files (or of project folders, with –each-project) Required.
Options
--project <PROJECT>: Project ID or slug (default: the context’s project, elsedefault) Environment:RUNBOOK_PROJECT.--each-project: Each subfolder of DIR is a project, named by its slug (–project is ignored)--dry-run: Validate and show what would change; change nothing--prune: Archive Git-managed runbooks that have no file in the folder--commit <COMMIT>: Commit recorded on new versions (default: $GITHUB_SHA, elsegit rev-parse HEAD)--branch <BRANCH>: Branch recorded on new versions (default: $GITHUB_HEAD_REF or $GITHUB_REF_NAME, else the checked-out branch)--idempotency-key <IDEMPOTENCY_KEY>: Idempotency key (one per project is derived from it)--json: Output the result as JSON
runbook sync pull
Section titled “runbook sync pull”Write each runbook’s latest published source to a folder (to start a repository from the app)
runbook sync pull <DIR> [OPTIONS]Arguments
DIR: Folder to write <runbook>.yaml files into (created if missing) Required.
Options
--project <PROJECT>: Project ID or slug (default: the context’s project, elsedefault) Environment:RUNBOOK_PROJECT.--each-project: Every project you can read, each into DIR/<project-slug>/ (–project is ignored)--json: Output what was written as JSON
runbook version
Section titled “runbook version”Show this CLI’s release and the server’s release and schema
runbook version [OPTIONS]Options
--json: Print JSON