Cadences and catch-up
A schedule’s cadence is one of four modes, each with a precise next-run rule.
Cadence modes
Section titled “Cadence modes”| Mode | Next-run rule |
|---|---|
hourly / daily / weekly / monthly / yearly | Wall-clock recurrence anchored on the chosen instant, computed in the schedule’s IANA timezone - DST-aware, month-length clamped |
every_n_minutes | Fixed interval from the anchor |
cron | A standard 5/6-field cron expression |
once | Fires a single time at the anchor, then disables itself |
Wall-clock presets
Section titled “Wall-clock presets”The presets anchor on the instant you pick. A daily schedule anchored at Tuesday 09:00 fires every day at 09:00 in the schedule’s timezone. Two edge cases are handled for you:
- DST transitions. The recurrence is computed in the schedule’s timezone, so a 09:00 daily run stays at 09:00 local time through clock changes. It does not drift by an hour twice a year.
- Month-length clamping. A monthly schedule anchored on the 31st fires on the last day of shorter months instead of skipping them.
Cron expressions
Section titled “Cron expressions”For cadences the presets can’t express, use a standard cron expression (5-field, or 6-field with seconds):
| Expression | Fires |
|---|---|
0 18 * * 1-5 | Weekdays at 18:00 |
30 6 1 * * | The 1st of every month at 06:30 |
0 9,17 * * * | Daily at 09:00 and 17:00 |
*/10 8-18 * * 1-5 | Every 10 minutes during business hours, weekdays |
Cron schedules also carry a timezone. The expression is evaluated in that timezone, not in UTC, unless UTC is what you pick.
Fixed intervals and one-shots
Section titled “Fixed intervals and one-shots”every_n_minutes fires on a fixed interval from the anchor, which is useful
for polling-style flows. once fires a single time at the anchor and then
disables itself. It is a scheduled hand-off, not a recurrence.
End conditions
Section titled “End conditions”A schedule can bound itself:
until <datetime>disables the schedule once the end instant passes.max_runs <n>disables the schedule after its n-th firing.
Exceeding either condition disables the schedule rather than deleting it. The configuration, run count, and last status remain visible.
Catch-up policies
Section titled “Catch-up policies”The catch-up policy decides what happens to runs that were missed while the host was down, such as when the laptop was closed, the instance was restarting, or the daemon was stopped.
| Policy | Behavior | Use when |
|---|---|---|
skip | Advance the timer only; missed windows never run | Frequent runs where only the cadence matters (polling, smoke tests) |
run-once (default) | A single make-up run, then resume the normal cadence | Most flows - the work happens, without replaying a backlog |
run-all | Replay each missed slot | Runs whose per-window output matters (per-day reports, per-window exports) |
Combined with timer advancement before execution, catch-up is deterministic. A host that was down over three daily windows runs zero, one, or three make-up runs. The count follows your policy, never an accident.
Previewing
Section titled “Previewing”The schedule picker previews the next firings before you save, for whatever you configure across presets, cron, intervals, end conditions, and timezone. The CLI exposes the same recurrence math, and the engine’s next-run rules are unit-tested against DST and month-boundary cases.