automations

name	automations
description	Create and manage bb automations from the first-party automations plugin. Use when scheduling recurring or one-shot agent/script work with bb automation commands.

Automations

An automation is a scheduled task. When due it runs in one of two modes:

agent Spawn a thread or re-prompt a target thread with a configured prompt. script Run a stored server-side script and capture stdout/stderr/exit.

Use bb plugin run automations ... while the kernel bb automation command still exists; once the kernel command is removed, bb automation ... will route to this plugin command.

Pass --project explicitly for every automation command. Inside a thread, automations are stamped origin agent and record the creating thread automatically. Automation-spawned threads cannot create automations.

Choosing a mode:

Use script when the output is fully determined by code: watchdogs, threshold alerts, health checks, heartbeats, and API pollers with a fixed output shape. Scripts run on the bb server, with cwd inside the plugin data directory's scripts/ area. Script automations do not have an environment field and do not accept environment flags.

Design the script to print nothing when there is nothing to report: an exit-0 run with empty stdout/stderr, or a last non-empty line of {"wakeAgent": false}, is recorded as a skipped silent tick. Any other output is captured; non-zero exit or timeout is recorded as a failed run.

Use agent when the run needs reasoning: summarize a feed, pick interesting items, draft a human-friendly message, or branch on content.

Creating:

bb plugin run automations create --project <id> --name "..." [schedule flags] [mode flags]

Schedule flags:

--cron <expr>                  Recurring 5-field cron expression
--timezone <tz>                IANA timezone for --cron
--at <datetime>                One-shot run time, preferably ISO 8601
--in <duration>                One-shot delay, e.g. 30s, 5m, 2h, 1d

Agent mode flags:

--prompt <prompt>              Prompt to run when due
--provider <id>                Provider ID
--model <model>                Model ID
--permission-mode <mode>       accept-edits, auto, or full
--target-thread <id>           Reuse/re-prompt an existing thread
--environment <id-or-path>     Existing environment ID or unmanaged workspace path
--new-environment <kind>       Create a new environment (worktree)
--base-branch <branch>         Base branch for new managed worktrees

When --permission-mode is omitted, the plugin chooses Approve for me (auto) when the provider supports it and otherwise uses Full Access (full).

Script mode flags:

--script <inline>              Inline script content
--script-file <path>           Read script content from a local file
--interpreter <name>           bash, sh, node, or python3
--timeout <ms>                 Timeout in milliseconds, default 120000, max 900000
--env-json <json>              Script variables as a string-to-string JSON object

Script environment variables:

BB_SERVER_URL          The bb server API base URL
BB_PROJECT_ID          The automation's project
BB_AUTOMATION_ID       The automation id
BB_AUTOMATION_RUN_ID   This run id

BB_ENVIRONMENT_ID and BB_HOST_DAEMON_PORT are intentionally not injected by the plugin. The plugin resolves bb and prepends its directory to PATH so scripts can call the CLI.

Managing:

bb plugin run automations list --project <id>
bb plugin run automations show <automationId> --project <id>
bb plugin run automations update <automationId> --project <id> [--name <name>] [schedule flags] [complete execution flags | partial agent update flags]
bb plugin run automations pause <automationId> --project <id>
bb plugin run automations resume <automationId> --project <id>
bb plugin run automations run <automationId> --project <id> [--idempotency-key <key>]
bb plugin run automations runs <automationId> --project <id> [--limit <count>] [--output <runId>]
bb plugin run automations delete <automationId> --project <id> --yes

Choose one of two execution update forms:

• A complete replacement uses --prompt, --provider, and --model together to replace the execution with an agent, or --script/--script-file to replace it with a script. Include every desired mode-specific setting; settings from the previous execution do not carry over.
• A partial agent update omits --provider and --model, preserves every omitted execution field, and edits the existing agent automation in place. Use any combination of --prompt and --permission-mode accept-edits|auto|full, then choose at most one execution target:

bb plugin run automations update <automationId> --project <id> \
  --environment <environment-id-or-path>
bb plugin run automations update <automationId> --project <id> \
  --target-thread <thread-id>
bb plugin run automations update <automationId> --project <id> \
  --new-environment worktree [--base-branch <branch>]

--target-thread, --environment, and --new-environment are mutually exclusive. These flags apply only to agent automations; script automations have no execution environment.

Every command supports --json.