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

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