Cron jobs

A cron job runs a container on a schedule and then exits. Use it for work that happens at a time rather than in response to an event: nightly reports, cache warming, data syncs, cleanup.

Create one

guidal cron create nightly-report \
  --image ghcr.io/your-org/your-app:v1 \
  --schedule "0 2 * * *" \
  --command "python -m app.reports.nightly"

The schedule is standard cron syntax, in UTC:

┌─ minute (0-59)
│ ┌─ hour (0-23)
│ │ ┌─ day of month (1-31)
│ │ │ ┌─ month (1-12)
│ │ │ │ ┌─ day of week (0-6, Sunday = 0)
│ │ │ │ │
0 2 * * *   → every day at 02:00 UTC
*/15 * * * * → every 15 minutes
0 9 * * 1   → Mondays at 09:00 UTC

Manage

guidal cron list
guidal cron get nightly-report
guidal cron update nightly-report --schedule "0 3 * * *"
guidal cron delete nightly-report

Run one immediately

Useful for testing without waiting for the schedule:

guidal cron trigger nightly-report

A manual trigger runs the same container the schedule would.

Pause and resume

guidal cron suspend nightly-report
guidal cron resume nightly-report

Suspending keeps the definition but stops new runs — better than deleting a job during an incident, since you keep the schedule and command.

See what happened

guidal cron history nightly-report
guidal logs query --service nightly-report

History shows each run and how it finished. A cron job's exit code is its result: zero is success, anything else is failure.

Writing a job that behaves

Exit with the right code. A script that catches every exception and exits zero reports success while doing nothing.

Make it idempotent. A job may run twice — a manual trigger overlapping a scheduled run, or a retry. Running twice should not double-charge anyone.

Keep it shorter than its interval. If a job scheduled every 15 minutes takes 20, runs overlap. Either make it faster or lengthen the interval.

Log start and finish. A job that logs nothing is indistinguishable from one that never ran.

Plan limits