﻿Give a task a [`cron`](/configuration/tasks/#cron) expression and RunWisp starts
it on that schedule. Every scheduled start becomes a run in the history, with
its exit code and output.

```toml title="runwisp.toml"
[tasks.heartbeat]
cron = "*/5 * * * *"
run  = "/usr/local/bin/heartbeat"
```

A task without `cron` runs only when you start it. Scheduled runs use each
[parameter's](/concepts/parameters/) default value.

## Cron syntax

The usual 5 fields: minute, hour, day of month, month, day of week.

| Expression              | Runs                                      |
| ----------------------- | ----------------------------------------- |
| `* * * * *`             | every minute                              |
| `*/5 * * * *`           | every 5 minutes                           |
| `0 * * * *`             | at the top of every hour                  |
| `0 2 * * *`             | every day at 02:00                        |
| `30 9 * * 1-5`          | at 09:30, Monday to Friday                |
| `0 0 1 * *`             | at midnight on the 1st of every month     |
| `0 0 L * *`             | at midnight on the last day of the month  |
| `0 9 15W * *`           | at 09:00 on the weekday nearest the 15th  |
| `0 9 * * FRI#3`         | at 09:00 on the third Friday of the month |
| `@hourly`               | at the top of every hour                  |
| `@daily` / `@midnight`  | every day at 00:00                        |
| `@weekly`               | Sundays at 00:00                          |
| `@monthly`              | the 1st at 00:00                          |
| `@yearly` / `@annually` | January 1st at 00:00                      |
| `@every 1h30m`          | every 90 minutes                          |

Fields take lists (`1,15`), ranges (`1-5`), and steps (`*/10`). A range can
wrap around: `22-2` in the hour field runs from 22:00 to 02:00, and `FRI-MON`
runs Friday to Monday. In the day of week field, both `0` and `7` mean Sunday.
Since 1.7, the day of month field also takes `L` (last day), `L-3` (three days
before the last), `LW` (last weekday) and `15W` (the weekday nearest the 15th,
never crossing into another month). The day of week field takes `FRI#3` (third
Friday) and `FRI#L` (last Friday). `@every` is a fixed interval that doesn't line up
with the clock.

For more than once a minute, add a seconds field in front. Plain 5-field
expressions run at second `:00`.

| Expression       | Runs                             |
| ---------------- | -------------------------------- |
| `*/30 * * * * *` | every 30 seconds (`:00`, `:30`)  |
| `15 * * * * *`   | once a minute, at second `:15`   |
| `0 */5 * * * *`  | every 5 minutes, at second `:00` |

`runwisp validate` checks every expression without starting anything.

## Running in another timezone

Cron expressions use the host's timezone unless you set one. Set it for the
whole daemon, or per task:

```toml title="runwisp.toml"
[daemon]
timezone = "Europe/Bratislava"   # every task without its own timezone

[tasks.nightly-backup]
# ...
cron     = "30 2 * * *"
timezone = "Atlantic/Faroe"      # this task only
```

See [`[daemon] timezone`](/configuration/daemon/#timezone) and
[`timezone`](/configuration/tasks/#timezone). An unknown zone name (a typo, or a
container image without `tzdata`) stops the config from loading; RunWisp never
falls back to UTC silently. The TUI start screen and the Web UI connection
indicator show which zone is in use.

### Daylight saving time

A schedule runs once per wall-clock time, even across a clock change:

- **Clocks go back:** a time like 02:30 happens twice, but the task runs once.
  The second one is recorded in the history as `dst_skipped`.
- **Clocks go forward:** a time that doesn't exist that day (02:00 when the
  clock jumps from 01:59 to 03:00) runs once at 03:00, instead of being skipped
  until the next day.

`@every` schedules are not affected. They count real elapsed time, not wall-clock
times, so `@every 30m` keeps running every 30 minutes through a clock change.

### Clock changes

When the system clock jumps (`date -s`, an NTP correction, a VM snapshot
restore, a laptop waking from sleep), the scheduler notices within 5 seconds
and plans from the new time:

- **Forward:** a tick the jump skipped over runs once, late. Ticks in between
  are not replayed and are not counted as missed.
- **Backward:** the next run is the next matching time on the new clock. A run
  stamped before the jump keeps its original time in the history.

## Catching up after downtime

When the daemon was down (a reboot, a deploy, a crash), scheduled runs didn't
happen. [`catch_up`](/configuration/tasks/#catch_up) decides how many of them
run when the daemon starts again:

```toml title="runwisp.toml"
[tasks.metrics-rollup]
# ...
cron     = "*/15 * * * *"
catch_up = 1      # default: run the most recent missed one
```

Use `0` for probes that only care about fresh data, and a higher number for
jobs where each run handles its own slice of time. A value above `1` needs
[`on_overlap = "queue"`](/configuration/tasks/#on_overlap), or the config is
rejected. RunWisp counts missed runs
from the task's last run, or from when it first saw the task, so a new install
doesn't replay old history.

If more runs were missed than `catch_up` allows, the oldest are dropped and the
daemon logs a warning with the task name and how many were dropped.

### Missed-run alerts

A missed run counts as a failure by default. On the restart that finds the gap,
RunWisp records one run with `end_reason = "missed"` and sends a failure alert
naming the task and how many runs were missed. It goes to the bell and to every
channel that gets the task's failures. This happens whatever `catch_up` is set
to, and the alert always reports the full count.

For a task that is expected to miss runs (a laptop that's off at night), take
`missed` out of its [`failures`](/configuration/tasks/#failures):

```toml title="runwisp.toml"
[tasks.daytime-sync]
# ...
cron     = "*/30 9-17 * * 1-5"
failures = ["-missed"]   # still recorded, but not a failure and no alert
```

Put the same line in [`[defaults]`](/configuration/defaults/) to do it for every
task.

## Spreading out start times

When many tasks share a start time (say, `0 3 * * *`), they all start at the
same second. [`jitter`](/configuration/tasks/#jitter) lets RunWisp spread them
out:

```toml title="runwisp.toml"
[tasks.backup-a]
# ...
cron   = "0 3 * * *"
jitter = "30m"

[tasks.backup-b]
# ...
cron   = "0 3 * * *"
jitter = "30m"
```

RunWisp starts jittered tasks one at a time. If nothing else jittered is
running, a task starts right on time. If several are due together, they take
turns, and none starts later than its `jitter`. Each task's latest start time is
fixed when the daemon starts, so the same config always gives the same order.
The run history shows both the scheduled time and the real start.

When three or more tasks without a `jitter` would start at the same second,
`runwisp validate` and the daemon at startup warn and name them. To see when
each schedule fires, run `runwisp validate --explain`.

## Pausing a schedule

Pause a task to stop its schedule without editing `runwisp.toml`, for example
while something it depends on is down:

```bash
runwisp pause nightly-backup
runwisp resume nightly-backup
```

In the Web UI and the TUI, click **Pause** on the task's page, or press <kbd>p</kbd>
on the task in the TUI. The REST API has `POST /api/tasks/{task}/pause` and `.../resume`.

While a task is paused, its scheduled times are skipped. They add no runs and
are not caught up when you resume or when the daemon restarts. You can still run
the task by hand. `runwisp status` lists paused tasks.

The pause survives `runwisp reload` and restarts. Pausing needs
[`manual_trigger`](/configuration/tasks/#manual_trigger) on, and a reload that
removes the task's [`cron`](/configuration/tasks/#cron) or sets `manual_trigger = false` clears the pause with
a warning. A task cron still runs ([held](/coming-from/cron/#held-jobs)) can't
be paused.

## After a crash

On a normal shutdown, every run gets a final status. After a hard crash (power
loss, `kill -9`) the daemon can't do that, so on the next start every run still
marked as running is ended as `crashed` with exit code `-2`. These runs are not resumed.
Catch-up may then start a fresh run. No run is ever left stuck on "running".

## Crontab jobs

Jobs read from a crontab with
[`include_cron`](/configuration/daemon/#include_cron) follow cron's rules: a
missed job is recorded but never run later.

## Changing the schedule

RunWisp reads `runwisp.toml` at startup and on `runwisp reload`, never on its
own. A task added by a reload gets no catch-up. See
[Reload & restart](/operations/reload/).
