launchd Job Builder

What it's for

Make a launchd job: the property list file macOS reads to start a program for you at login, on a schedule, every few seconds, when a file changes, or to keep it running. launchd takes the place of cron on a Mac, but its files are fiddly to write by hand and fail quietly when something is wrong.

For example, when you want a backup script to run at 2:30 every weekday morning, fill in its path and the schedule 30 2 * * mon-fri here, save the file into ~/Library/LaunchAgents and load it with the command given.

How to use it

Give the job a label (a reverse domain name such as com.example.backup, which also names the file) and choose the kind: an agent runs while you’re logged in, and a daemon runs for the whole Mac, even before anyone logs in (as root unless you name a user). The kind is remembered in this browser.

Put the program on the first line and each argument on a line of its own, as launchd runs the program directly. To use pipes, ~ or $VARIABLES, tick Run as a shell command, which runs the lines through /bin/zsh -c. Then choose when it runs: at load, every N seconds, on a cron schedule (turned into launchd’s StartCalendarInterval, with names such as mon and shortcuts such as @daily allowed), when paths change, or kept running. Log files, a working folder and environment variables are under Logs, folder and environment.

Mistakes are listed as you type. Save the .plist downloads the file, and the commands below it copy it into place, check it with plutil, load it, run it straight away, show its state and unload it.

Example

Press Try an example. It fills in an rsync backup that runs at 30 2 * * mon-fri and logs to /tmp/com.example.backup.log.

The message says Save it as ~/Library/LaunchAgents/com.example.backup.plist. The property list has StartCalendarInterval as an array of five entries, each with Minute 30, Hour 2 and a Weekday from 1 to 5, and the commands load it with launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.example.backup.plist.

Good to know

launchd doesn’t expand ~ or $VARIABLES in paths, doesn’t search your PATH beyond the system folders (so Homebrew programs need their full path), and doesn’t create the folder for a log file. A job scheduled while the Mac is asleep runs when it wakes, but one scheduled while it’s off is skipped. A program that reads your files may also need Full Disk Access in System Settings › Privacy & Security.