Schedule timed jobs on macOS with launchd

launchd is a robust scheduled job automation tool on macOS that allows you to schedule a task to be run at recurring times. It‘s macOS‘s take on Linux‘s cron. In this lesson, we’ll schedule a simple bash script that empties the Trash to run every Monday morning at 10am.

First, we’ll create a plist file (a plist file is just XML) with our job configuration. In here, we’ll specify our bash script as the program to run. Then we move plist file to the ~/Library/LaunchAgents folder. Then we’ll use launchctl to load our configuration file, which will make the job active. We‘ll manually activate our job to ensure it‘s working with launchctl kickstart.

To install the launchd job:

mv local.empty-trash.plist ~/Library/LaunchAgents
launchctl load ~/Library/LaunchAgents/local.empty-trash.plist

To verify it‘s active

launchctl list | grep ‘local‘

To run it immediately

launchctl kickstart gui/$UID/local.empty-trash

To unload the job

launchctl unload ~/Library/LaunchAgents/local.empty-trash.plist

Now if you grep for the job (launchctl list | grep ‘local‘), it won‘t be in that list.

/local.empty-trash.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.cameronnokes.personal.empty-trash</string>
    <key>ProgramArguments</key>
    <array>
      <string>/Users/cameronnokes/cron_empty-trash.sh</string>
    </array>
    <key>StartCalendarInterval</key>
    <dict>
      <key>Weekday</key>
      <integer>1</integer>
      <key>Hour</key>
      <integer>10</integer>
    </dict>
</dict>
</plist>

empty-trash.sh

#!/bin/bash                               
osascript -e ‘tell app "Finder" to empty‘ 

Additional notes

Launchd is actually a really huge topic and I only went over one of the most basic use cases of it. Here‘s some other things that I couldn‘t fit into the video.

Why not cron?

Launchd is really robust and has a lot more features than cron does (at least that‘s the case on macOS, the GNU/Linux crontab is different and more robust than the BSD cron AFAIK). For example, some other possiblities:

• StartInterval: Run job every N seconds
• StartOnMount: Run when a device has been mounted (for example a backup harddrive)
• WatchPaths: Run when creating, removing files in this directory
• RunAtLoad: Run at startup and login
• StandardOutPath and StandardErrorPath: specify where your stdio goes (otherwise it goes to the syslog I think)

See "Learn more" below for more.

Apple also recommends using launchd over cron. For small use cases like this one, I think cron is fine though, I suspect that recommendation is targeted for macOS app devs.

Why use AppleScript to empty the Trash and not rm -rf ~/.Trash?

There‘s a few edge cases with emptying the trash that rm doesn‘t handle. One of them was that if you have files from a different device in the trash then rm can run into permission issues deleting those.

Will my scheduled job run if my computer is off or asleep?

From Apple‘s documentation: "If you schedule a launchd job by setting the StartCalendarInterval key and the computer is asleep when the job should have run, your job will run when the computer wakes up. However, if the machine is off when the job should have run, the job does not execute until the next designated time occurs."

Learn more

http://www.launchd.info/
https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/ScheduledJobs.html
https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html

[Bash] Schedule Timed Jobs on macOS with `launchd`