Defining Schedules

Schedules trigger operations on a recurring basis using cron expressions. Use schedules for periodic syncs, cleanups, report generation, or any task that needs to run at regular intervals.

Schedule Interface


interface ApplyConfigScheduleInput {
  operationKey: string;                 // Key of the operation to trigger
  cron: string;                         // Cron expression (e.g., '0 2 * * *')
  timezone?: string;                    // IANA timezone (e.g., 'America/New_York')
  enabled?: boolean;                    // Whether the schedule is active (default: true)
  payload?: Record<string, unknown>;    // Static payload sent to the operation
}

Basic Example

Run an operation every night at 2:00 AM:


import { defineConfig, defineSchedule } from '@eide/foir-cli/configs';
 
export default defineConfig({
  key: 'my-app',
  name: 'My App',
  operations: [
    {
      key: 'nightly-sync',
      name: 'Nightly Sync',
      endpoint: '/sync/full',
    },
  ],
  schedules: [
    defineSchedule({
      operationKey: 'nightly-sync',
      cron: '0 2 * * *',
      timezone: 'America/New_York',
      enabled: true,
    }),
  ],
});

Cron Expressions

Schedules use standard five-field cron syntax:


┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-6, Sunday=0)
│ │ │ │ │
* * * * *

Common Patterns

Expression	Meaning
`0 * * * *`	Every hour, on the hour
`/15 * * *`	Every 15 minutes
`0 2 * * *`	Daily at 2:00 AM
`0 9 * * 1-5`	Weekdays at 9:00 AM
`0 0 * * 0`	Every Sunday at midnight
`0 0 1 * *`	First day of every month at midnight
`0 6,18 * * *`	Twice daily at 6:00 AM and 6:00 PM

Timezone Support

Specify an IANA timezone to control when the schedule runs relative to a specific region. If omitted, the schedule runs in UTC.


schedules: [
  {
    operationKey: 'morning-report',
    cron: '0 9 * * 1-5',
    timezone: 'Europe/London',
  },
]

Common timezone values:

Timezone	Region
`UTC`	Coordinated Universal Time
`America/New_York`	US Eastern
`America/Los_Angeles`	US Pacific
`Europe/London`	UK
`Europe/Berlin`	Central Europe
`Asia/Tokyo`	Japan
`Australia/Sydney`	Australia Eastern

Payload

Send static data to the operation each time the schedule fires:


schedules: [
  {
    operationKey: 'generate-report',
    cron: '0 8 * * 1',
    timezone: 'America/New_York',
    payload: {
      reportType: 'weekly-summary',
      recipients: ['team@example.com'],
    },
  },
]

The payload is included in the operation’s request body alongside the standard execution context.

Enabling and Disabling

Set enabled to false to pause a schedule without removing it from the config:


schedules: [
  {
    operationKey: 'experimental-job',
    cron: '0 3 * * *',
    enabled: false,  // Paused -- will not run
  },
]

Push the config again with enabled: true to resume.

Examples

Daily Content Sync


schedules: [
  {
    operationKey: 'full-sync',
    cron: '0 2 * * *',
    timezone: 'UTC',
    enabled: true,
  },
]

Hourly Cache Warm


schedules: [
  {
    operationKey: 'warm-cache',
    cron: '0 * * * *',
  },
]

Weekly Report with Payload


schedules: [
  {
    operationKey: 'send-report',
    cron: '0 9 * * 1',
    timezone: 'America/New_York',
    payload: {
      format: 'pdf',
      period: 'last-7-days',
    },
  },
]

Next Steps

Defining Operations — Create the operations that schedules trigger
Defining Hooks — Trigger operations on content events instead of time
Configuration Reference — Full config API reference