Regular is a job scheduler like cron and anacron.

• Configuration using Starlark, a small configuration language based on Python. You can use expressions like hour in [9, 18] and minute == 0 to define when a job will run.
• Flexible scheduling based on current time and the last completed job
• Jitter to mitigate the thundering herd problem
• Job queues to configure what jobs run sequentially and in parallel
• Built-in logging and status reporting
• Built-in email notifications on localhost
• Hot reloading of job configuration on file change

You will need Go 1.22 or later:

go install dbohdan.com/regular@latest

Jobs are defined in Starlark files named config.star in subdirectories of the config directory. For example:

# Run if at least a day has passed since the last run
# and it isn't the weekend.
def should_run(finished, timestamp, dow, **_):
    return dow not in [0, 6] and timestamp - finished >= one_day

# Random delay of up to 1 hour.
jitter = one_hour

# Kill the job if it runs longer than this.
# 0 (default) means no timeout.
timeout = one_hour

# Command to run.
command = [
    "sh",
    "-c",
    "backup.sh ~/docs /backup/docs",
]

# Queue name (the default is the name of the job directory).
queue = "backup"

# Write output to log files (default).
log = True

# When to send notifications: "always", "on-failure" (default), "never".
notify = "always"

# Allow multiple instances in queue (default).
duplicate = False

# Enable/disable the job (default).
enable = True

Each job directory can also have an optional job.env file with environment variables:

PATH=${PATH}:${HOME}/bin
BACKUP_OPTS=--compress

• regular [flags] command
  • -h, --help Print help
  • -V, --version Print version number and exit
  • -c, --config-dir Path to config directory
  • -s, --state-dir Path to state directory

Start the scheduler:

• regular start

Run specific jobs once:

• regular run [--force] [job-names...]

Check job status:

• regular status [-l lines] [job-names...]

View application log:

• regular log [-l lines]

List available jobs:

• regular list

Default paths (override with -c and -s):

• Config: ~/.config/regular/

  • Global environment: ~/.config/regular/global.env
  • Job config: ~/.config/regular/<job>/config.star
  • Job environment: ~/.config/regular/<job>/job.env
  • Job executable (script): ~/.config/regular/<job>/job

• State: ~/.local/state/regular/

  • App log: ~/.local/state/regular/app.log
  • Database: ~/.local/state/regular/state.sqlite3
  • Lock file: ~/.local/state/regular/app.lock. When in use, this file prevents multiple instances of regular start from running at the same time. regular run also takes this lock when no daemon is running.
  • Logs for the latest job: ~/.local/state/regular/<job>/{stdout,stderr}.log. These logs and earlier logs are also stored in the database.

• Daemon socket: $XDG_RUNTIME_DIR/regular/socket (or, with no runtime dir, a per-user subdir under $TMPDIR). Set REGULAR_SOCK to override. The socket is created with mode 0600 and the client refuses to connect to one owned by another user.

The config and state directory are created automatically when you run regular start or regular run.

Job logs are truncated at 256 KiB. There is currently no built-in way to remove old logs from the database. You can use the sqlite3 command shell to remove logs manually.

All files and directories are created with 0600 and 0700 permissions respectively.

Regular's repository includes a systemd unit file for running the scheduler automatically as your user. Installation requires replacing %USER% with your username.

To install and enable the service, clone the repository, then run:

cd systemd/
# Run this as your user, not as root.
./install.sh

This will:

• Create a service file in ~/.config/systemd/user/
• Enable the service to start automatically
• Start the service immediately

To check the service status:

systemctl --user status regular

To view logs:

journalctl --user -u regular -f

Regular includes shell completions for the fish shell.

To install completions for the fish shell, clone the repository, then run:

cd completions/
./install.fish

This will copy the completion file to your fish configuration directory.

MIT. See the file LICENSE.