Bee Box documentation · directory: https://beebox.run/docs/reference/cards/ · index: https://beebox.run/docs/reference/cards/index.md · root: https://beebox.run/llms.txt

# scheduled-script Card

# Scheduled Script Cards

Scheduled scripts define commands to run on a schedule. They live in `_config/schedules/`.

## Schedule Types (mutually exclusive)
- **cron**: Standard cron expression (e.g., `0 6 * * *` for 6am daily)
- **at**: ISO datetime for a one-shot future execution
- **rrule**: iCalendar RRULE for complex recurrence patterns

## Frontmatter Fields
- **not-before**: Minimum time since last run. Prevents running more often than this interval even if the schedule says otherwise. Use duration strings: `5m`, `1h`, `4h`, `1d`.
- **on-wakeup**: If `true`, also run opportunistically during `bbx wakeup`, subject to not-before.
- **once**: If `true`, the card is deleted after successful execution.
- **until**: ISO datetime after which this schedule expires.
- **enabled**: Set to `false` to disable without deleting. This is per-box state, not part of the shipped definition — a disabled schedule still receives upstream definition updates (new cron/runs/description) while staying disabled.
- **budget**: Max cumulative runtime within a window. Format: `"LIMIT/WINDOW"` (e.g., `"10m/5h"` = max 10 minutes of runtime in any 5-hour window). Scripts exceeding their budget are skipped until the window clears.
- **lock-group**: Named concurrency group. Scripts sharing a lock-group won't run concurrently — if one is already running, others in the same group are skipped.
- **timeout**: Max runtime for a single run, as a duration string (e.g. `25m`). Counts only awake time (machine sleep doesn't eat the budget). Default: `10m`. The run is killed when it exceeds this.
- **runs**: The command to execute (required). Runs with cwd set to box root.
- **description**: Human-readable summary of what this schedule does.
- **source**: Why this schedule exists. Either a plain string, or `{text?, ref?}` to link to a related card.
- **create-after-success**: Optional array of `{path, args?}` entries. Create a card at `path` after successful execution; `args` are template arguments. Skipped if the target file already exists.
- **requires**: Optional `{connectors: [name, ...]}`. The schedule won't run if any required connector isn't configured for this box.

## Guidelines
- Set reasonable not-before values to prevent hammering external services.
- Use on-wakeup for things that should happen whenever the agent is active.
- For one-shot future tasks, combine `at` with `once: true`.

## Templates

### scheduled-script

A scheduled script card — declarative scheduling for commands

```bash
bbx create <path>.scheduled-script.card -t scheduled-script
```

Template: scheduled-script
Description: A scheduled script card — declarative scheduling for commands
Card types: scheduled-script

Arguments:
  runs: The command to execute
  description (optional): Human-readable summary of what this schedule does
  cron (optional): Cron expression (e.g., `0 6 * * *`)
  at (optional): ISO datetime for one-shot execution
  rrule (optional): iCalendar RRULE string
  notBefore (optional): Minimum interval since last run (e.g., '5m', '1h')
  onWakeup (optional): Also run during bbx wakeup
  once (optional): Delete after successful execution
  source (optional): Why this schedule exists
  lock-group (optional): Named concurrency group