README.md

run-on-macos-screen-unlock

A tiny Swift program to run a command whenever the screen unlocks
(I use it for remounting network shares when waking from sleep)

# run-on-macos-screen-unlock <command-to-run-on-unlock> [command-args]
run-on-macos-screen-unlock ./examples/mount-network-shares.sh

# add to launchctl (start on login)
serviceman add --user \
    --path "$PATH" \
    ./run-on-macos-screen-unlock ./examples/mount-network-shares.sh

Table of Contents

• Install
• Run on Login
  • With serviceman
  • With a plist template
• Build from Source
• Publish Release
• Similar Products

Install

1. Download

   curl --fail-with-body -L -O https://github.com/coolaj86/run-on-macos-screen-unlock/releases/download/v1.0.0/run-on-macos-screen-unlock-v1.0.0.tar.gz

2. Extract

   tar xvf ./run-on-macos-screen-unlock-v1.0.0.tar.gz

3. Allow running even though it's unsigned

   xattr -r -d com.apple.quarantine ./run-on-macos-screen-unlock

4. Move into your PATH

   mv ./run-on-macos-screen-unlock ~/bin/

Run on Login

You'll see notifications similar to these when adding launchctl services yourself:

With serviceman

1. Install serviceman

   curl --fail-with-body -sS https://webi.sh/serviceman | sh
   source ~/.config/envman/PATH.env

2. Register with Launchd
   (change COMMAND_GOES_HERE to your command)

   serviceman add --user \
       --path "$PATH" \
       ~/bin/run-on-macos-screen-unlock COMMAND_GOES_HERE

With a plist template

1. Download the template plist file

   curl --fail-with-body -L -O https://raw.githubusercontent.com/coolaj86/run-on-macos-screen-unlock/main/examples/run-on-macos-screen-unlock.COMMAND_LABEL_GOES_HERE.plist

2. Change the template variables to what you need:

   • USERNAME_GOES_HERE (the result of $(id -u -n) or echo $USER)
   • COMMAND_LABEL_GOES_HERE (lowercase, dashes, no spaces)
   • COMMAND_GOES_HERE (the example uses ./examples/mount-network-shares.sh)

3. Rename and move the file to ~/Library/LaunchDaemons/

   mv ./run-on-macos-screen-unlock.COMMAND_LABEL_GOES_HERE.plist ./run-on-macos-screen-unlock.example-label.plist
   mv ./run-on-macos-screen-unlock.*.plist ~/Library/LaunchDaemons/

4. Register using launchctl

   launchctl load -w ~/Library/LaunchAgents/run-on-macos-screen-unlock.*.plist

View logs

tail -f ~/.local/share/run-on-macos-screen-unlock.*/var/log/run-on-macos-screen-unlock.*.log

Build from Source

1. Install XCode Tools
   (including git and swift)

   xcode-select --install

2. Clone and enter the repo

   git clone https://github.com/coolaj86/run-on-macos-screen-unlock.git
   pushd ./run-on-macos-screen-unlock/

3. Build with swiftc

   swiftc ./run-on-macos-screen-unlock.swift

Publish Release

1. Git tag and push

   git tag v1.0.x
   git push --tags

2. Create a release
   https://github.com/coolaj86/run-on-macos-screen-unlock/releases/new
3. Tar and upload

   tar cvf ./run-on-macos-screen-unlock-v1.0.x.tar ./run-on-macos-screen-unlock
   gzip ./run-on-macos-screen-unlock-v1.0.x.tar
   open .

Similar Products

• How to run a command on lock/unlock (the snippets from which this repo grew)
• EventScripts
• HammarSpoon: caffeinate.watcher