launchd

The service manager of macOS. A launch agent in ~/Library/LaunchAgents starts a script for the user on a schedule, like cron.

launchd starts and schedules programs on macOS. My pCloud backup runs as a launch agent every night at 02:00.

A launch agent

A property list in ~/Library/LaunchAgents/, for example de.adrian.pcloud-backup.plist, with a Label, the ProgramArguments, a StartCalendarInterval (hour and minute) and log paths. ProcessType Background and LowPriorityIO keep it out of the way. The agent runs as the user and sees the same configuration as the user's terminal.

plutil -lint ~/Library/LaunchAgents/<label>.plist
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/<label>.plist   # load
launchctl kickstart gui/$(id -u)/<label>                                 # run now
launchctl print gui/$(id -u)/<label> | grep 'last exit'                  # last exit code
launchctl bootout gui/$(id -u)/<label>                                   # unload

Behaviour to know

  • If the Mac sleeps at the scheduled time, the run follows on wake; if it is switched off, the run is skipped.
  • bootout stops the agent at once, but launchd loads the plist again at the next login. Renaming the file switches it off for good.
  • A launch agent starts with a minimal PATH; scripts set it themselves.
  • macOS privacy protection (TCC) keeps background jobs out of ~/Desktop, ~/Documents and ~/Downloads; they see these folders as empty.

More on this

Used in
  • Encrypted pCloud Backup with rclone Guide: a nightly, client-side encrypted backup from the Mac to pCloud with rclone and launchd, with a 90-day archive and tested restores.

Show in the graph view →