My Little Corner of the Net

Mac OS X: Automating Tasks on Sleep

I’ve been playing a lot lately with AppleScript and the Mac Automater app, both of which can do some pretty cool stuff. This gave me an idea: wouldn’t it be great if I could close certain applications when my commuters go to sleep?

I have a handful of programs that I run on both my MacBook and Mac Pro desktop at work, using file syncing tools like Dropbox or BTSync to keep the data files up to date on both machines. This generally works great, except that I have to remember to close the programs when I switch machines, otherwise I sometimes end up with unexpected results like locked files or, in some cases, data loss. I’m not so good at this and Apple doesn’t appear to provide a way to do it for me.

It didn’t take long, however, to find a free third-party utility that does. Sleepwatcher is a small daemon process that monitors the sate of your system and kicks off a shell script when certain system events occur. It can monitor for events such as sleep and wake up, display sleep and dimming, and even system idle (a specified period with no keyboard or mouse activity) and power status (when a MacBook switches from AC to battery power and vice-versa). It can also prevent the machine from sleeping based on the result of a script or it can run a script when another process prevents the system from sleeping. Sleepwatcher can be run as a system process (always running in the background, even when no users are logged in), as a user process for individual logged-in users, or both.

Before we get too far along, it should be noted that this may not be the best approach for all applications. The method I’m about to describe works best with applications that save their data files automatically, and exit without user intervention. While the applications will be shut down in a clean manner, you may have unexpected results if the application prompts you to save or to confirm that you really want to quit.

It is also very important to note that you should be extremely careful when implementing these scripts. An improper configuration could render your machine unable to sleep, wakeup, or even boot, so be sure to carefully test your scripts before enabling them to run automatically.

Installing Sleepwatcher from the developer’s site is a bit tricky as it comes with no installer and assumes some knowledge of the Unix command line. A much easier way to install it is to use a package manager such as Homebrew (I believe MacPorts can also install Sleepwatcher, but I’ve only done it with Homebrew). If you aren’t familiar with Homebrew, it is definitely worth checking out.

Assuming that you have Homebrew installed and working correctly, installing Sleepwatcher is as easy as running the following command in a terminal window:

brew install sleepwatcher

Homebrew will download and install Sleepwatcher at /usr/local/sbin/sleepwatcher. Note the followup instructions that Homebrew provides after installation, as we’ll get to them in a moment. Once the installation is is done, I recommend reading the man page, as it is the best way to get to know everything Sleepwatcher can do:

man sleepwatcher

Now it’s time to write a sleep script. As we’ll find out in a moment, Sleepwatcher looks for user scripts named ~/.sleep and ~/.wakeup and system scripts named /etc/rc.sleep and /etc/rc.wakeup. Since we want to close programs that are running under our own UID, let’s choose the local user option.

First, create a file named .sleep in your home directory using your editor of choice (mine is vi for this kind of stuff):

vi ~/.sleep

Then add the following to the file (in this example, I’m going to close the program KeePassX, my password manager, using AppleScript):

#!/bin/bash
osascript -e 'tell application "KeyPassX" to quit'

If you want to close additional applications, simply add another osascript command for each additional application.

Why use AppleScript instead of something more bash-like, such as kill? AppleScript works inside the application, telling it to do a clean exit, such as if I pressed Comand-Q to close it myself. This allows the program to make sure files are saved and everything is in order before the process ends. Kill simply aborts the running process, regardless of what’s happening, which could result in data loss and other instabilities, which we’re trying to prevent in the first place.

After the script is saved, you’ll need to give it execute premissions:

chmod 700 ~/.sleep

New we’re ready to test the script. Enter the following in a terminal window to start Sleepwatcher:

/usr/local/sbin/sleepwatcher --verbose --sleep ~/.sleep

You won’t see anything happen; in fact, it will look like the terminal is hanging. Make sure KeePassX (or whatever program you added to the .sleep file) is running and then close the lid of your MacBook (or go to Apple Menu > Sleep if you aren’t on a MacBook). Wait until the computer’s power light starts to slowly blink on and off, and then wake it by opening the lid and/or pressing the power button. The computer should resume exactly as you left it except that your target application should no longer be running. If anything went wrong, check the terminal window where you ran Sleepwatcher, it should show any errors that occurred. Press Control-C to stop Sleepwatcher.

Now it is time to configure launchd to run Sleepwatcher at startup or login. To do this, we need to add a plist file to our user or system’s LaunchAgents directory. Sleepwatcher comes with sample plist files that handle the four use cases mentioned above: user sleep, user wakeup, system sleep, and system wakeup.

If you only need support for sleep and wakeup, you can simply symlink the sample files to the proper LauchAgents directories. For this activity we only need to set up the user LaunchAgent since we aren’t using any system scripts:

ln -sfv /usr/local/Cellar/sleepwatcher/2.2/de.bernhard-baehr.sleepwatcher-20compatibility-localuser.plist ~/Library/LaunchAgents/

Then we tell launchd to load the configuration:

launchctl load ~/Library/LaunchAgents/de.bernhard-baehr.sleepwatcher-20compatibility-localuser.plist

Although not required in this example, to install the system agent, do the following:

sudo ln -sfv /usr/local/Cellar/sleepwatcher/2.2/de.bernhard-baehr.sleepwatcher-20compatibility.plist /Library/LaunchAgents/
sudo launchctl /Library/LaunchAgents/de.bernhard-baehr.sleepwatcher-20compatibility.plist

Note that you’ll need to be an administrator of the machine to install the system agent.

That’s about all there is to it! Sleepwatcher is now running in the background waiting for your computer to go to sleep. When they system does, Sleepwatcher will kick off your .sleep script and, when the system resumes, Sleepwatcher will run your .wakeup script (if you create one). And, since you also added the plist file to your LaunchAgents directory, launchd will find it and start Sleepwatcher every time your machine starts up or whenever you log in.

If you want to script other events, such as system idle or power status, you’ll need to make a copy of the sample plist file(s) and edit them by hand. Understanding the plist file format should be fairly straightforward if you compare the sample with the options described on the man page. Xcode features a graphical plist editor, but plists are simple XML files, so you can edit them in any text editor if you prefer.

Do you have a creative use for Sleepwatcher? Let me know about it in the comments.

22 Comments to Mac OS X: Automating Tasks on Sleep

  1. 02/13/2014 at 9:30 am | Permalink

    Thanks for this Kodiak,

    I’m using sleepwatcher to halt Vagrant boxes and clear hosts files on sleep, it’s great to be able to manage the package with brew.

    One thing that drove me a bit crazy, in your examples above you have a typo:

    LuanchAgents should be LaunchAgents

  2. Mike m's Gravatar Mike m
    02/17/2016 at 8:38 am | Permalink

    Hi, this is a great article as I am trying to replicate a similar event on waking up my mac from sleep. I am running OSX EL Capitan – and for some reason, when I awake from a sleep state, the mail app is active on my desktop, even when the window is closed (but active in the dock). Not sure if this is a bug, but I haven’t been able to find any way to fix this other than running sleepwatcher until apple figures out the issue. I have installed Sleepwatcher correctly, typing “man sleepwatcher” I do get a text return in terminal. I have made a .”wakeup” file in my home location (/Users/GHOST/hidemail.wakeup/hide\ mail.scpt) and have written my script to hide mail:
    tell application “System Events”
    set visible of process “Mail” to false
    end tell
    – and saved it to the .wakeup file in the home location. I am not sure where to take it from here. I understand I need to add the plist file to the launch agent directory, just not sure what the plist should show? Thanks in advance for the help.

  3. 05/16/2016 at 5:13 pm | Permalink

    It was very useful. I used for same reason of Kevin: vagrant.
    Thank very much Kodiak.

  4. Arun's Gravatar Arun
    12/24/2016 at 1:57 pm | Permalink

    Hi, this is great. I have a couple of questions.

    1. Where can I find the logs output of the sleep or wakeup script ?
    2. How do I add enhancements to sleepwatcher ? Is it open source ?

  5. 02/08/2017 at 1:51 pm | Permalink

    You can get logs by adding the following to the plist file

    StandardOutPath/tmp/sleepwatcher.out
    StandardErrorPath/tmp/sleepwatcher.err

  6. 10/04/2017 at 12:18 pm | Permalink

    Super useful, thanks Kodiak! I had the exact same use case, using DropBox as a “backend” for my KeePassX files. Not sure what I did wrong, but I had to deviate from your .sleep structure slightly to get it to work:

    #!/bin/bash
    osascript -e ‘tell application “KeePassX”
    quit
    end tell’

    Anyway, thanks again!

  7. Dis's Gravatar Dis
    11/24/2017 at 9:48 pm | Permalink

    Hi Kodiak!

    I’m trying to figure out how to trigger a script after login from the screensaver. Sleepwatcher works on resume from sleep or a fresh login, but not from a screensaver login.

    Any tips?

    Cheers,
    Dis

  8. Pablo's Gravatar Pablo
    03/04/2019 at 6:24 pm | Permalink

    Thanks! I’ve used this to auto turn on/off Philips Hue lights of my studio when computer awakes/sleeps

  9. Marius's Gravatar Marius
    07/11/2020 at 9:54 pm | Permalink

    Thanks for those clear explanations. I’m using it to turn all internet connections off and back on while computer is asleep.

    As of July 2020 the software is running v2.2.1, you want to make sure to specific ln -sfv /usr/local/Cellar/sleepwatcher/2.2.1/de.bernhard-baehr.sleepwatcher-20compatibility-localuser.plist ~/Library/LaunchAgents/ for it to work properly.

  10. 08/28/2020 at 6:45 am | Permalink

    Thank you Marius for the update! Thank you for the grate work having this program. 😉

  11. philo's Gravatar philo
    05/06/2022 at 12:49 am | Permalink

    Hi! Thanks for everything. I’m stuck at the launchd load configuration, that fails with the message “Load failed: 5: Input/output error
    Try running `launchctl bootstrap` as root for richer errors.”

    I don’t know what to do!!

    Any hints?

  12. SubZero's Gravatar SubZero
    06/11/2022 at 11:30 am | Permalink

    Great write up, just what I needed to solve an issue with my 2.5GB USB NIC failing after sleep.

    As of 11 June 2022, macOS 12.4 – I had to use this command to activate the user plist


    ln -sfv /opt/homebrew/Cellar/sleepwatcher/2.2.1/homebrew.mxcl.sleepwatcher.plist ~/Library/LaunchAgents/

  13. Dean's Gravatar Dean
    08/06/2022 at 11:57 am | Permalink

    Kodiak,

    This article was super helpful, sleepwatcher is the exact tool I needed to automate some tasks and make my life much easier, but finding documentation (and good documentation) on it was extremely difficult. One thing I might mention is that when I installed sleepwatcher using homebrew, my files were in /opt/homebrew, so the commands were slightly different for me (probably because this article was written 8 years ago):

    “ln -sfv /usr/local/Cellar/sleepwatcher/2.2/de.bernhard-baehr.sleepwatcher-20compatibility-localuser.plist ~/Library/LaunchAgents/”
    was instead
    “ln -sfv /opt/homebrew/Cellar/sleepwatcher/2.2.1/homebrew.mxcl.sleepwatcher.plist ~/Library/LaunchAgents/”

    and naturally,

    “launchctl load ~/Library/LaunchAgents/de.bernhard-baehr.sleepwatcher-20compatibility-localuser.plist”
    was instead
    “launchctl load ~/Library/LaunchAgents/homebrew.mxcl.sleepwatcher.plist”

    Hopefully this helps if anyone ends up being stuck on not being able to find the necessary files.

    It was really surprising and relieving that an 8 year old article helped me implement something I’d been struggling with for a few hours. It seems like the sky is the limit for automating tasks (both useful and for fun) now that this is working on my computer.

    Thanks again Kodiak, you’re a lifesaver!

  14. Dude's Gravatar Dude
    02/13/2023 at 12:23 pm | Permalink

    Kodiak (and/or anyone having the same issue),
    I tried this on macOS Monterey 12.6.3, specifically the display sleep trigger “-S .displaysleep” and it does not seem to be working. Running the command prompted me to grant “Input Monitoring” privacy access, but even after doing so and re-launching the command putting the display to sleep (via a hot corner) did not run the script despite it being set to mode 700. Any assistance here would be greatly appreciated.

  1. By on 06/20/2014 at 8:25 am
  2. By on 11/06/2021 at 8:53 am
  3. By on 11/08/2021 at 3:36 am
  4. By on 11/24/2021 at 1:56 am
  5. By on 02/02/2024 at 1:37 pm

Leave a Reply

You can use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>

<