CLI reference
sundial <command> [flags]
Commands
| Command | What it does |
|---|---|
| serve | Stay up and run jobs on schedule. The only long-running command. |
| check | Parse the config, print the next five runs per job. Non-zero exit on any problem. |
| run <job> | Run one job now, in the foreground, with its output on the terminal. |
| log <job> | Print recorded runs for a job: start, duration, exit code. |
| list | One line per job: name, schedule, last exit code, last run. |
| version | Version, commit and build date. |
Global flags
| Flag | Default | Meaning |
|---|---|---|
| -c, --config | ~/.config/sundial/jobs.conf | Config file path. |
| --state | ~/.local/state/sundial | Where the run log lives. |
| --json | false | Machine-readable output for list and log. |
| --dry-run | false | With run: print the command instead of executing it. |
Job fields
| Field | Required | Meaning |
|---|---|---|
| run | yes | Command line. Executed without a shell unless it contains a pipe or redirect. |
| schedule | yes | See schedule syntax. |
| timeout | no | Kill the run after this long. Default: none. |
| tz | no | IANA zone for at schedules. |
| workdir | no | Working directory. Default: the directory of the config file. |
| env | no | Extra environment, as { KEY = "value" }. |
| on_fail | no | "ignore" (default), "notify", or a command to run. |
Running under systemd
# /etc/systemd/system/sundial.service
[Unit]
Description=sundial
After=network-online.target
[Service]
ExecStart=/usr/local/bin/sundial serve -c /etc/sundial/jobs.conf
Restart=on-failure
RestartSec=5s
User=sundial
[Install]
WantedBy=multi-user.target
Reload the config without dropping running jobs by sending SIGHUP; jobs already
executing finish under their old definition.
Exit codes
| Code | Meaning |
|---|---|
| 0 | Success. |
| 1 | Runtime error — a job failed, or the state directory is not writable. |
| 2 | Config error. check uses this for anything that does not parse. |
| 3 | The named job does not exist. |