# schedules

Explains how to run Windmill scripts and flows on a cron schedule, including the six-field cron format and file layout.

Skill by Windmill. Category: Shipping and ops.

## Install

Project (for this project only):

```sh
npx skills add windmill-labs/windmill-cli-docs --skill schedules
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

Global (for every project on this machine):

```sh
npx skills add windmill-labs/windmill-cli-docs --skill schedules -g
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

## Tags

- Runs on your computer: It runs as a program on your machine, with your access.

## Security audits

- Gen Agent Trust Hub: Pass
- Socket: Pass
- Snyk: Pass

Installs: 20. Installs counted by skills.sh. [Open on skills.sh](https://www.skills.sh/windmill-labs/windmill-cli-docs/schedules)

## Source

[Open the source](https://github.com/windmill-labs/windmill-cli-docs/tree/HEAD/skills/schedules). Checked 2026-10-10. This summary may contain AI-generated text, so it can be wrong. Check the source before you rely on it.

## SKILL.md

````markdown
---
name: schedules
description: MUST use when configuring schedules.
---

# Windmill Schedules

Schedules run scripts and flows automatically on a cron schedule.

## File Naming

Schedule files use the pattern: `{path}.schedule.yaml`

Example: `f/folder/daily_sync.schedule.yaml`

Note: The path is derived from the filename, not stored in the file content.

## Cron Expression Format

Windmill uses 6-field cron expressions (includes seconds):

```
 ┌───────────── second (0-59)
 │ ┌───────────── minute (0-59)
 │ │ ┌───────────── hour (0-23)
 │ │ │ ┌───────────── day of month (1-31)
 │ │ │ │ ┌───────────── month (1-12 or jan-dec)
 │ │ │ │ │ ┌───────────── day of week (0-6, 0=Sunday, or sun-sat)
 │ │ │ │ │ │
 * * * * * *
```

**Common Examples:**
- `0 0 0 * * *` - Daily at midnight
- `0 0 12 * * *` - Daily at noon
- `0 */5 * * * *` - Every 5 minutes
- `0 0 9 * * 1-5` - Weekdays at 9 AM
- `0 0 0 1 * *` - First day of each month

## CLI Commands

Deploying local changes to the workspace can be destructive to remote state — only suggest/run a deploy when the user explicitly asks to deploy/publish/push, not when they say "run", "try", or "test". Deploy via `git push` or `wmill sync push` depending on how the repo is wired (see the **Deploying** section in `AGENTS.wmill.md`). The commands below never mutate remote state, so they're safe to run yourself — note that `sync pull` does overwrite local files to match the remote (use `sync pull --dry-run` to only preview), while `schedule` just lists.

```bash
# Push schedules to Windmill — only when the user explicitly asks to deploy
wmill sync push

# Pull schedules from Windmill
wmill sync pull

# List schedules
wmill schedule
```


## Schedule (`*.schedule.yaml`)

Must be a YAML file that adheres to the following schema:

```yaml
type: object
properties:
  schedule:
    type: string
    description: Cron expression with 6 fields (seconds, minutes, hours, day of month,
      month, day of week). Example '0 0 12 * * *' for daily at noon
  timezone:
    type: string
    description: IANA timezone for the schedule (e.g., 'UTC', 'Europe/Paris', 'America/New_York')
  enabled:
    type: boolean
    description: Whether the schedule is currently active and will trigger jobs
  script_path:
    type: string
    description: Path to the script or flow to execute when triggered
  is_flow:
    type: boolean
    description: True if script_path points to a flow, false if it points to a script
  args:
    type: object
    description: The arguments to pass to the script or flow
  on_failure:
    type: string
    description: Path to a script or flow to run when the scheduled job fails
  on_failure_times:
    type: number
    description: Number of consecutive failures before the on_failure handler is triggered
      (default 1)
  on_failure_exact:
    type: boolean
    description: If true, trigger on_failure handler only on exactly N failures, not
      on every failure after N
  on_failure_extra_args:
    type: object
    description: The arguments to pass to the script or flow
  on_recovery:
    type: string
    description: Path to a script or flow to run when the schedule recovers after
      failures
  on_recovery_times:
    type: number
    description: Number of consecutive successes before the on_recovery handler is
      triggered (default 1)
  on_recovery_extra_args:
    type: object
    description: The arguments to pass to the script or flow
  on_success:
    type: string
    description: Path to a script or flow to run after each successful execution
  on_success_extra_args:
    type: object
    description: The arguments to pass to the script or flow
  ws_error_handler_muted:
    type: boolean
    description: If true, the workspace-level error handler will not be triggered
      for this schedule's failures
  retry:
    type: object
    properties:
      constant:
        type: object
        description: Retry with constant delay between attempts
        properties:
          attempts:
            type: integer
            description: Number of retry attempts
          seconds:
            type: integer
            description: Seconds to wait between retries
      exponential:
        type: object
        description: 'Retry with exponential backoff: the n-th retry waits multiplier
          × seconds^n'
        properties:
          attempts:
            type: integer
            description: Number of retry attempts
          multiplier:
            type: integer
            description: Multiplier for exponential backoff
          seconds:
            type: integer
            minimum: 1
            description: Base of the exponential (seconds); the n-th retry waits multiplier
              × seconds^n, where n counts constant retries too
          random_factor:
            type: integer
            minimum: 0
            maximum: 100
            description: Random jitter percentage (0-100) to avoid thundering herd
      retry_if:
        $ref: '#/components/schemas/RetryIf'
    description: Retry configuration for failed module executions
  summary:
    type: string
    description: Short summary describing the purpose of this schedule
  description:
    type: string
    description: Detailed description of what this schedule does
  no_flow_overlap:
    type: boolean
    description: If true, skip this schedule's execution if the previous run is still
      in progress (prevents concurrent runs)
  tag:
    type: string
    description: Worker tag to route jobs to specific worker groups
  paused_until:
    type: string
    description: ISO 8601 datetime until which the schedule is paused. Schedule resumes
      automatically after this time
  cron_version:
    type: string
    description: Cron parser version. Use 'v2' for extended syntax with additional
      features
  dynamic_skip:
    type: string
    description: Path to a script that validates scheduled datetimes. Receives scheduled_for
      datetime and returns boolean to skip (true) or run (false)
  labels:
    type: array
    items:
      type: string
  draft_only:
    type: boolean
    description: 'True when this row is a per-user draft with no deployed

      schedule at the same path. Frontend renders a "Draft" badge.

      '
  is_draft:
    type: boolean
    description: 'True when the authed user has a per-user draft at this path

      (over a deployed row or a synthesized draft-only row).

      Frontend appends a `*` to the displayed name.

      '
  inherited_labels:
    type: array
    items:
      type: string
    description: 'Labels inherited from the parent folder, computed at read time.
      Read-only — edit them on the folder.

      '
required:
- schedule
- script_path
- timezone
- is_flow
- enabled
```
````

- Previous: [resources](https://syn4pse.dev/terminal/windmill-resources.md)
- Next: [write-script-bash](https://syn4pse.dev/terminal/windmill-write-script-bash.md)
- [Terminal](https://syn4pse.dev/terminal.md)
- [Suggest a change](mailto:terminal@syn4pse.dev?subject=Terminal%20suggestion)
