sleepwatcher(8)

📦 version 2.2.1, in nixpkgs unstable

✨ NAME ✨

Hey bestie! Welcome to the sleepwatcher(8) manual page — the System Manager's Manual for your new fave daemon. 💖

sleepwatcher — daemon to monitor sleep, wakeup and idleness of a Mac

🌸 SYNOPSIS 🌸

sleepwatcher [-n] [-v] [-V] [-d] [-g] [-f configfile] [-p pidfile]
             [-a[allowsleepcommand]] [-c cantsleepcommand]
             [-s sleepcommand] [-w wakeupcommand] [-D displaydimcommand]
             [-E displayundimcommand] [-S displaysleepcommand]
             [-W displaywakeupcommand] [-t timeout -i idlecommand
             [-R idleresumecommand]] [-b break -r resumecommand]
             [-P plugcommand] [-U unplugcommand]

🦋 DESCRIPTION 🦋

Okay so sleepwatcher is literally that girl — a program that monitors sleep, wakeup and idleness of a Mac. It can execute a Unix command when the Mac or the display of the Mac goes to sleep mode or wakes up, after a given time without user interaction or when the user resumes activity after a break or when the power supply of a Mac notebook is attached or detached. It also can send the Mac to sleep mode or retrieve the time since last user activity. No cap, it does it all. 💅

Command line options:

  • -n, --now — Sleep now and exit, ignoring other options. Like, immediate main character energy. 😴
  • -v, --version — Display version and copyright information and exit. Show me your ID, bestie. 🪪
  • -V, --verbose — Log any action sleepwatcher performs, either to stdout or, when running as daemon, to the syslog. It's giving "tell me everything." 🗣️
  • -d, --daemon — Run as background daemon. Don't use this option when starting sleepwatcher via launchd(8). Lowkey important — read that again. 🚫
  • -g, --getidletime — Print the time (in 0.1 seconds) of no keyboard or mouse activity to stdout and exit, ignoring other options. Just a quick vibe check on your idle time. ⏱️
  • -f configfile, --config configfile — Read additional configuration options from configfile. configfile contains options in the form option [ = value ] where option is one of the long command line options (without --). sleepwatcher rereads its configuration file when it receives a hangup signal, SIGHUP. Okay so it's a whole mood — it can refresh its fit. 🔄
  • -p pidfile, --pidfile pidfile — Write the process id of sleepwatcher to pidfile. Keep track of bae's location. 📍
  • -a[allowsleepcommand], --allowsleep[=allowsleepcommand] — Allow the Mac to idle sleep only when allowsleepcommand returns a zero exit code. Without allowsleepcommand, this option prevents idle sleep at all. When the -a option is not used at all, sleepwatcher allows idle sleep unconditionally. (Note: no space after the -a.) 🛑 This one's got lore — it's the permission slip.
  • -c cantsleepcommand, --cantsleep cantsleepcommand — Execute cantsleepcommand when the Mac retracts an attempt to sleep that was previously allowed by the -a option, but vetoed by another process that wants to prevent idle sleep. Note that the kernel notifies sleepwatcher about the retracted sleep only when it previously asked it if sleeping is allowed. There might be canceled idle sleep attempts without the -a and -c commands executed at all. 😭 The drama. The betrayal.
  • -s sleepcommand, --sleep sleepcommand — Execute sleepcommand when the Mac is put to sleep mode. sleepcommand must not take longer than 15 seconds because after this timeout the sleep mode is forced by the system. ⏰ Bestie, do NOT overstay your welcome.
  • -w wakeupcommand, --wakeup wakeupcommand — Execute wakeupcommand when the Mac wakes up from sleep mode. Rise and shine, queen. 🌞
  • -D displaydimcommand, --displaydim displaydimcommand — Execute displaydimcommand when the display of the Mac is dimmed. Note that the displaydimcommand is executed when the Mac goes to sleep mode, too. Dim the lights, it's giving mood lighting. 💡
  • -E displayundimcommand, --displayundim displayundimcommand — Execute displayundimcommand when the display of the Mac is undimmed without having gone to sleep. Note that the displayundimcommand is not executed when the Mac or the display of the Mac wakes up from sleep mode. So petty — it only un-dims for the specific case. 🙈
  • -S displaysleepcommand, --displaysleep displaysleepcommand — Execute displaysleepcommand when the display of the Mac is put to sleep mode. Screen's sleeping, not the whole Mac. ✨
  • -W displaywakeupcommand, --displaywakeup displaywakeupcommand — Execute displaywakeupcommand when the display of the Mac wakes up from sleep mode. Note that the displaywakeupcommand is executed when the Mac wakes up from sleep mode, too. Double duty, she's versatile. 🔥
  • -t timeout, --timeout timeout — Set the timeout (in 0.1 seconds) for the -i option, i. e. execute idlecommand after this time of no user interactivity. The patience level. ⏳
  • -i idlecommand, --idle idlecommand — Execute idlecommand after the time of no user interactivity set with the -t option. When you're bored, this runs. 🎮
  • -R idleresumecommand, --idleresume idleresumecommand — Execute idleresumecommand when the user resumes input after the -i command was executed due to an idle time. Welcome back, bestie! 🫶
  • -b breakduration, --break breakduration — Set the breakduration (in 0.1 seconds) for the -r option, i. e. execute resumecommand when the user resumes input after a break of at least this duration. How long is a "break"? You decide. ☕
  • -r resumecommand, --resume resumecommand — Execute resumecommand when the user resumes keyboard or mouse activity after a break with a duration given with the -b option. Gryffindor! 🦁
  • -P plugcommand, --plug plugcommand — Execute plugcommand when a Mac notebook is connected to the power supply. Charging szn. 🔌
  • -U unplugcommand, --unplug unplugcommand — Execute unplugcommand when a Mac notebook is disconnected from the power supply. On battery, living free. 🔋

🎀 SEE ALSO 🎀

pmset(1), launchd(8), SystemStarter(8)

💀 BUGS 💀

The -t -i and -b -r options only work when the Mac OS X GUI is running, so they cannot be used when sleepwatcher is started as a system-wide launchd(8) agent during system startup. 🚫 Like, sorry bestie, no GUI no idle party.
Any user with execute permission for sleepwatcher can send the Mac to sleep mode with the -n option, making the system unavailable for other (remote) users. 😳 Highkey a prank waiting to happen — protect your perms!

👑 ACKNOWLEDGEMENTS 👑

Thanks to Daniel Griscom for the idea and code for the deny sleep feature. Thanks to Darren Creutz for the idea and code for the display sleep support. Thanks to Michael Lee for the ideas for idleness handling within sleepwatcher. Thanks to Brian Jenkins for the idea and code for the power supply feature. And thanks to Louis Pan for the idea and code for the can't sleep callback. 💖 Y'all ate, fr fr.

This page is from Darwin, dated Fri Apr 2 2010. Bye bestie! 💅✨

📦 where this page comes from