> ## Documentation Index
> Fetch the complete documentation index at: https://doc.trycapsule.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# capsule schedule

> Manage backup schedules for your database connections.

<Note>
  Scheduled backups require a **Solo plan or above**. Hobbyist accounts can still connect databases and run manual backups — the Schedule option simply won't appear in the TUI menu, and the CLI subcommands below will return an upgrade error. Upgrade your plan from the [billing page](https://trycapsule.xyz/dashboard/billing) to unlock it.
</Note>

## Subcommands

| Command                   | Description                                         |
| ------------------------- | --------------------------------------------------- |
| `capsule schedule add`    | Add or update a schedule for a connection           |
| `capsule schedule list`   | List all configured schedules                       |
| `capsule schedule remove` | Permanently remove a schedule                       |
| `capsule schedule pause`  | Pause a schedule without losing its cron expression |
| `capsule schedule resume` | Resume a paused schedule                            |

***

## capsule schedule add

```bash theme={null}
capsule schedule add --connection <label> --cron "<cron expression>"
```

### Flags

| Flag                 | Description                                                                                                                        |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `--connection`, `-c` | Connection label to schedule (required)                                                                                            |
| `--cron`, `-e`       | Cron expression for backup frequency (required)                                                                                    |
| `--timezone`, `-z`   | IANA timezone the cron expression is evaluated in, e.g. `"America/New_York"` (optional — defaults to the server's own system time) |

Re-running `add` for a connection that already has a schedule updates its cron expression (and timezone, if passed) in place and un-pauses it if it was paused.

### Why `--timezone` matters

By default, a cron expression like `0 2 * * *` means "2 AM in whatever timezone your server's clock is set to" — which may well not be your own timezone. If your server runs on UTC and you're several hours ahead or behind, "2 AM" on the server can land at a very different hour on your own clock, which is a common source of confusion ("I scheduled a 2 AM backup, why did the email show up at 3 AM?").

Pass `--timezone` with an IANA zone name (e.g. `Africa/Lagos`, `America/New_York`, `Europe/London` — the same names used by most operating systems and the `tz` database) to make the schedule run at 2 AM in *that* zone specifically, regardless of what timezone the server itself is set to:

```bash theme={null}
capsule schedule add --connection prod-postgres --cron "0 2 * * *" --timezone "Africa/Lagos"
```

<Tip>
  Not sure of the exact IANA name for your timezone? Browse the full list at [nodatime.org/TimeZones](https://nodatime.org/TimeZones) and copy the name exactly as shown (e.g. `Europe/London`, `Asia/Kolkata`).
</Tip>

An invalid or misspelled timezone name is rejected immediately with an error, before anything is saved.

**When to run:** After adding a new database connection that you want backed up automatically. Every connection you care about should have a schedule — unscheduled connections only get backed up when you manually trigger one.

### Cron expression examples

A cron expression is just five space-separated fields, in this order: **minute, hour, day-of-month, month, day-of-week**. A `*` means "any" — so `0 2 * * *` reads as "at minute 0, hour 2, any day of the month, any month, any day of the week," i.e. every day at 2:00 AM.

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

| Expression    | Meaning                  |
| ------------- | ------------------------ |
| `0 2 * * *`   | Every day at 2:00 AM     |
| `0 2 * * 0`   | Every Sunday at 2:00 AM  |
| `0 */6 * * *` | Every 6 hours            |
| `0 2 1 * *`   | First day of every month |

<Tip>
  In case you're not familiar with cron syntax, or just don't want to work it out by hand, use [crontab.guru](https://crontab.guru) — build your expression there field by field and it shows you in plain English exactly what it means, so you can confirm it says what you intended before using it here.
</Tip>

***

## capsule schedule list

```bash theme={null}
capsule schedule list
```

Lists all configured schedules with their cron expression, last-run time, and paused state. If a schedule has a timezone set, it's shown alongside the cron expression; schedules without one (the default) just show the expression on its own, meaning server-local time.

```
  prod-postgres  (0 2 * * *  Africa/Lagos)   last: 2026-07-05T02:00:00Z
  staging-mysql  (0 */6 * * *)               last: never  [paused]
```

**When to run:** To confirm your schedules are set up correctly, or to find a schedule's cron expression before editing it.

***

## capsule schedule remove

```bash theme={null}
capsule schedule remove --connection <label>
```

Permanently deletes the schedule for a connection. The connection itself is not affected — only the schedule is deleted, and you'd need to run `add` again with a cron expression to bring it back.

**When to run:** When decommissioning a database, or removing a schedule that was set up incorrectly. If you just want to temporarily stop backups without losing the cron expression, use `pause` instead.

***

## capsule schedule pause / resume

```bash theme={null}
capsule schedule pause --connection <label>
capsule schedule resume --connection <label>
```

Pausing keeps the schedule's cron expression and last-run history intact — it just tells the daemon to skip it. Resuming picks up right where it left off. This is the safer option when you want to temporarily stop a schedule (e.g. during a maintenance window) without having to re-type the cron expression afterward.

Both the TUI (press `Ctrl+D` on the Schedule screen) and these CLI subcommands do the same thing under the hood.

***

## Live reload

Every subcommand above tries to signal the running daemon to reload its schedules immediately, so the change takes effect without a full daemon restart or any interruption to a backup that happens to be running at that moment. When it succeeds, you'll see:

```
Daemon reloaded — change applied immediately.
```

If the daemon isn't reachable (not running, or a permissions mismatch), you'll see a fallback message instead:

```
Restart the daemon to apply changes: sudo systemctl restart capsule
```

In that case, run the suggested command to apply the change.

***

## Notes

* Schedules are stored in `~/.config/capsule/capsule.yaml` and executed by the `capsule daemon` process
* The daemon must be running for scheduled backups to fire — install it as a service with `sudo capsule install-service` if you haven't already. See [capsule service](/cli/service)
* Schedule changes sync to your dashboard automatically; a sync failure (e.g. offline) is logged as a warning but doesn't block the local change
* The timezone (if set) syncs along with everything else, and is shown next to the schedule on the [dashboard](/dashboard/schedules)