automations ยท diff
git:20261023.ce200df to git:20261023.611d35b
15 added, 15 removed. Audit A to A.
---
name: automations
- description: "Schedule or manage recurring and one-shot BB agent or script automations."
+ description: "Schedule or manage recurring and one-shot HYPERFIDE agent or script automations."
---
# 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 the top-level `bb automation` command. The CLI routes it to this plugin.
+ Use the top-level `Hyperfide automation` command. The CLI routes it to this plugin.
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.
- Personal supports automations with `--project proj_personal`. Use `bb project list --include-personal --json` to include it in discovery; an empty default project list does not mean Personal is unavailable.
+ Personal supports automations with `--project proj_personal`. Use `hyperfide-platform project list --include-personal --json` to include it in discovery; an empty default project list does not mean Personal is unavailable.
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. New standard-project scripts use the server-host project source when one exists; Personal and projects without one run in the plugin's shared script storage directory. Existing scripts without a saved policy also run there. Use `--working-directory automation-storage|project|<absolute-server-path>` to select the policy. Script automations do not have an environment field and do not accept environment flags.
+ 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 hyperfide-platform server. New standard-project scripts use the server-host project source when one exists; Personal and projects without one run in the plugin's shared script storage directory. Existing scripts without a saved policy also run there. Use `--working-directory automation-storage|project|<absolute-server-path>` to select the policy. 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:
```bash
- bb automation create --project <id> --name "..." [schedule flags] [mode flags]
+ Hyperfide automation create --project <id> --name "..." [schedule flags] [mode flags]
```
For creation flags and mode-specific defaults, read
[references/creation.md](references/creation.md).
Read `references/script-runtime.md` before you use a script file, depend on
injected variables, or diagnose retries, timeouts, restarts, and silent runs.
Managing:
```bash
- bb automation list --project <id>
- bb automation list --target-thread <threadId>
- bb automation show <automationId> --project <id>
- bb automation update <automationId> --project <id> [--name <name>] [schedule flags] [complete execution flags | partial agent update flags]
- bb automation pause <automationId> --project <id>
- bb automation resume <automationId> --project <id>
- bb automation run <automationId> --project <id> [--idempotency-key <key>]
- bb automation runs <automationId> --project <id> [--limit <count>] [--output <runId>]
- bb automation delete <automationId> --project <id> --yes
+ Hyperfide automation list --project <id>
+ Hyperfide automation list --target-thread <threadId>
+ Hyperfide automation show <automationId> --project <id>
+ Hyperfide automation update <automationId> --project <id> [--name <name>] [schedule flags] [complete execution flags | partial agent update flags]
+ Hyperfide automation pause <automationId> --project <id>
+ Hyperfide automation resume <automationId> --project <id>
+ Hyperfide automation run <automationId> --project <id> [--idempotency-key <key>]
+ Hyperfide automation runs <automationId> --project <id> [--limit <count>] [--output <runId>]
+ Hyperfide automation delete <automationId> --project <id> --yes
```
`list --target-thread` returns automations in any project that re-prompt that
thread; the thread's Info tab shows the same list. It does not include
automations the thread merely created.
For partial updates, mode replacement, execution targets, or damaged records,
read [references/updates.md](references/updates.md). Every command supports `--json`.
- `bb automation <command> --help` prints that command's exact arguments, options,
+ `Hyperfide automation <command> --help` prints that command's exact arguments, options,
accepted values, and rules. Unknown commands, unknown options, and stray
arguments are rejected rather than ignored, and a failure under `--json` also
prints a `{"ok":false,"error":{"code","message","hint"}}` envelope on stdout.