# ry cron

> Run something of an app on a schedule: call a path (the app is woken) or run a command on its own machine.

```text
ry cron [options] [command]
```

## Subcommands

### `ry cron list`

The app's schedules: when, what, the next slot and the last run.

```text
ry cron list [options] <app>
```

Alias: `ls`.

Example:

```bash
ry cron list web
```

### `ry cron add`

Add a schedule: ry cron add `<app>` `"<expr>"` --path /tick, or --command `"<shell>"` for a machine of its own.

```text
ry cron add [options] <app> <schedule> [command...]
```

Options:

- `--timezone <zone>`: IANA time zone the expression is read in (default UTC), e.g. Europe/Berlin.
- `--path <path>`: The app is woken and this path is called, e.g. /api/tick.
- `--method <method>`: With --path: GET (default) or POST.
- `--command <shell>`: Runs on a machine of its own, as /bin/sh -c `'<shell>'` (or give the argv after --).
- `-t, --timeout <seconds>`: Deadline (--path: per attempt, default 60, at most 240; --command: default 900, at most 3600).
- `-m, --memory <mb>`: With --command: memory of its machine in MB (default: the app's).
- `-c, --vcpus <n>`: With --command: vCPUs of its machine (default: the app's).
- `--paused`: Create it paused (ry cron resume starts it).

Example:

```bash
ry cron add web "*/15 * * * *" --path /api/tick
ry cron add web "0 3 * * *" --timezone Europe/Berlin --command "npm run cleanup"
```

From `ry cron add --help`:

```text
The expression has five fields (minute hour day-of-month month day-of-week) or is @hourly, @daily, ...

Examples:
  ry cron add shop "*/15 * * * *" --path /api/tick
  ry cron add shop "0 3 * * *" --timezone Europe/Berlin --command "npm run cleanup" --memory 8192
  ry cron add shop "@daily" -- node scripts/report.js --full

--path suits frequent, light work: down to every minute, the app does it in its own machine.
--command suits heavy, rare work: at most hourly, every run gets a machine of its own size.
A slot that comes while the previous run of the same schedule still runs is skipped, not queued.

A path is called signed: header Rytiv-Cron-Signature = v1=<hex HMAC-SHA256 of '<Rytiv-Cron-Timestamp>.<path>'>
under the app's secret RYTIV_CRON_SECRET (created with the app's first --path schedule; the app sees it from its next deploy).
```

### `ry cron rm`

Remove a schedule and its run history.

```text
ry cron rm [options] <app> <id>
```

Alias: `remove`.

Options:

- `-y, --yes`: Confirm without asking (automation).

Example:

```bash
ry cron rm web sch-1a2b3c4d --yes
```

### `ry cron pause`

Stop starting runs (the schedule and its run log stay).

```text
ry cron pause [options] <app> <id>
```

Example:

```bash
ry cron pause web sch-1a2b3c4d
```

### `ry cron resume`

Start running again, from the next slot on (nothing paused is caught up).

```text
ry cron resume [options] <app> <id>
```

Example:

```bash
ry cron resume web sch-1a2b3c4d
```

### `ry cron runs`

The newest runs of a schedule: slot, state, attempts, answer, duration, reason.

```text
ry cron runs [options] <app> <id>
```

Options:

- `-n, --limit <n>`: How many (default 20, at most 100).

Example:

```bash
ry cron runs web sch-1a2b3c4d
```

### `ry cron run`

Run a schedule once, now (to try the target without waiting for its slot).

```text
ry cron run [options] <app> <id>
```

Example:

```bash
ry cron run web sch-1a2b3c4d
```