Skip to content

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.

These work with every command.

  • --host <HOST>: Runbook server host URL
  • --context <CONTEXT>: Configured context name to use
  • context: Manage CLI contexts
  • spec: Manage and validate runbook specs
  • run: Manage and inspect executions
  • step: Agent loop: next, claim, heartbeat, log, report
  • whoami: Show which credentials and host the CLI uses
  • me: Current user tasks and inbox
  • user: Pilot administration: users
  • project: Pilot administration: projects and project roles
  • team: Pilot administration: teams and team members
  • login: Store a personal access token for the current host
  • logout: Forget the stored token for the current host
  • token: Create, list and revoke personal access tokens
  • apps: List and disconnect the OAuth apps (MCP clients) you connected
  • webhook: Manage webhook subscriptions and deliveries
  • memory: Search, save and manage runbook memory
  • archive: List and download runbook execution archives
  • list: List a project’s runbooks
  • get: Show a runbook, its latest published version, input schema and step outline
  • pull: Write a runbook’s draft source to a file or stdout
  • push: Create or update a runbook from a file and publish it (–draft saves only)
  • publish: Publish a runbook’s current draft
  • diff: Compare a local spec file with the published runbook, or two published versions
  • mcp: Model Context Protocol server
  • skill: Manage and install agent skills
  • sync: 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

Manage CLI contexts

runbook context <COMMAND>

Commands

  • add: Add or update a context
  • use: Switch current context
  • list: List all contexts
  • remove: Remove a context and forget its login

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

Switch current context

runbook context use <NAME>

Arguments

  • NAME: Context name Required.

List all contexts

runbook context list [OPTIONS]

Options

  • --json: Output as JSON

Remove a context and forget its login

runbook context remove <NAME>

Arguments

  • NAME: Context name Required.

Manage and validate runbook specs

runbook spec <COMMAND>

Commands

  • validate: Validate a runbook spec offline

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

Manage and inspect executions

runbook run <COMMAND>

Commands

  • start: Start an execution
  • get: Get an execution’s details
  • list: List executions
  • watch: Watch execution events in real time
  • signal: Send a signal to an execution
  • report: View an execution report
  • cancel: Cancel an execution
  • pause: Pause an execution
  • resume: Resume an execution
  • update: Update execution metadata
  • rerun: Rerun an execution
  • fields: Manage execution fields
  • token: Mint an execution access/refresh pair

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

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

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

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

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

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 of md, 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

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

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

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

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

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

Manage execution fields

runbook run fields <COMMAND>

Commands

  • set: Set execution fields

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

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)

Agent loop: next, claim, heartbeat, log, report

runbook step <COMMAND>

Commands

  • next: Show the resume brief: completed work and ready steps
  • get: Read the step you claimed: instructions, checklist and pinned skill (claim first)
  • skill-file: Read one file of the claimed step’s pinned skill
  • claim: Claim a ready step run (then read it with step get)
  • heartbeat: Extend the current claim’s lease
  • log: Append stdin lines to the step’s log
  • report: Report the step’s result
  • evidence: Upload an evidence file for the step run
  • checklist: Set the step’s checklist (ticked items complete, the rest open)
  • decide: Decide an approval
  • release: Release a claim (or, with –reason, an admin release)
  • request-human: Hand the step to a person
  • exec: Run a local command as the claimed step’s work: stream its output as logs, heartbeat, and report by exit code

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

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

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)

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

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

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

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 of succeeded, failed.
  • --verdict <VERDICT>: Check verdict, independent of status One of pass, 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

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

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

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

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

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

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

Show which credentials and host the CLI uses

runbook whoami [OPTIONS]

Options

  • --json: Output as JSON

Current user tasks and inbox

runbook me <COMMAND>

Commands

  • tasks: List open tasks and approvals for the current user

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

Pilot administration: users

runbook user <COMMAND>

Commands

  • create: Create a user in the organization
  • deactivate: Deactivate a user
  • list: List users in the organization

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

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

List users in the organization

runbook user list [OPTIONS]

Options

  • --org <ORG>: Organization ID (default: the only one visible)
  • --json: Output response as JSON

Pilot administration: projects and project roles

runbook project <COMMAND>

Commands

  • create: Create a project
  • member: Grant or revoke project roles

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

Grant or revoke project roles

runbook project member <COMMAND>

Commands

  • add: Grant a user a project role
  • remove: Revoke a user’s project role
  • list: List project members

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 of viewer, operator, editor, admin. Default viewer.
  • --org <ORG>: Organization ID (default: the only one visible)
  • --idempotency-key <IDEMPOTENCY_KEY>: Idempotency key
  • --json: Output response as JSON

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

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

Pilot administration: teams and team members

runbook team <COMMAND>

Commands

  • create: Create a team
  • list: List teams in the organization
  • member: Add or remove team members

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

List teams in the organization

runbook team list [OPTIONS]

Options

  • --org <ORG>: Organization ID (default: the only one visible)
  • --json: Output response as JSON

Add or remove team members

runbook team member <COMMAND>

Commands

  • add: Add a user to a team
  • remove: Remove a user from a team

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

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

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

Forget the stored token for the current host

runbook logout [OPTIONS]

Options

  • --json: Output as JSON

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 tokens
  • revoke: Revoke a token

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

List your tokens

runbook token list [OPTIONS]

Options

  • --json: Output response as JSON

Revoke a token

runbook token revoke <TOKEN> [OPTIONS]

Arguments

  • TOKEN: Token ID (tok_…) Required.

Options

  • --json: Output response as JSON

List and disconnect the OAuth apps (MCP clients) you connected

runbook apps <COMMAND>

Commands

  • list: List the OAuth apps (MCP clients) you connected
  • revoke: Disconnect an OAuth app: its tokens stop working now

List the OAuth apps (MCP clients) you connected

runbook apps list [OPTIONS]

Options

  • --json: Output response as JSON

Disconnect an OAuth app: its tokens stop working now

runbook apps revoke <CLIENT> [OPTIONS]

Arguments

  • CLIENT: Client ID (from runbook apps list) Required.

Options

  • --json: Output response as JSON

Manage webhook subscriptions and deliveries

runbook webhook <COMMAND>

Commands

  • list: List a project’s webhook subscriptions
  • create: Create a subscription (prints its signing secret once)
  • update: Update a subscription; omitted options are unchanged
  • delete: Delete a subscription and its delivery log
  • test: Send a webhook.test event to a subscription
  • deliveries: Show a subscription’s delivery log
  • redeliver: Send a delivery’s event again under a new delivery ID
  • rotate-secret: Rotate the signing secret (prints the new secret once)

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

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

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

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

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

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

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

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

Search, save and manage runbook memory

runbook memory <COMMAND>

Commands

  • search: Search a runbook’s active memory
  • save: Save a durable fact for future runs: live at once, or a proposal with –propose
  • edit: 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)

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

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

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

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

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

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

Unlock a memory entry (people only)

runbook memory unlock <MEM> [OPTIONS]

Arguments

  • MEM: Memory ID (mem_…) Required.

Options

  • --json: Output response as JSON

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

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 (from memory list --proposed); refused if it changed Required.
  • --json: Output response as JSON

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

Archive a memory entry (people only)

runbook memory archive <MEM> [OPTIONS]

Arguments

  • MEM: Memory ID (mem_…) Required.

Options

  • --json: Output response as JSON

List and download runbook execution archives

runbook archive <COMMAND>

Commands

  • list: List a runbook’s daily archive files
  • download: Download daily archive files or range bundle

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

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)

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

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

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

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

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

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

Model Context Protocol server

runbook mcp <COMMAND>

Commands

  • serve: Run a stdio MCP server using the current context

Run a stdio MCP server using the current context

runbook mcp serve

Manage and install agent skills

runbook skill <COMMAND>

Commands

  • list: List project skills and versions with runbook usages
  • push: Upload a skill folder (SKILL.md plus supporting files)
  • pull: Download a skill folder from the project
  • install: Install skills into an agent’s skill directory

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

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

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

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 of claude, codex, cursor.
  • --scope <SCOPE>: Installation scope: user or project One of user, project. Default user.
  • --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

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 batch
  • pull: Write each runbook’s latest published source to a folder (to start a repository from the app)

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, else default) 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, else git 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

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, else default) 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

Show this CLI’s release and the server’s release and schema

runbook version [OPTIONS]

Options

  • --json: Print JSON