Add Inspect Assertions Preventing Sleep as a Mac TIL

README.md

@@ -10,7 +10,7 @@ pairing with smart people at Hashrocket.
 
 For a steady stream of TILs, [sign up for my newsletter](https://crafty-builder-6996.ck.page/e169c61186).
 
-_1678 TILs and counting..._
+_1679 TILs and counting..._
 
 See some of the other learning resources I work on:
 
@@ -706,6 +706,7 @@ If you've learned something here, support my efforts writing daily TILs by
 - [Find The Process Using A Specific Port](mac/find-the-process-using-a-specific-port.md)
 - [Gesture For Viewing All Windows Of Current App](mac/gesture-for-viewing-all-windows-of-current-app.md)
 - [Insert A Non-Breaking Space Character](mac/insert-a-non-breaking-space-character.md)
+- [Inspect Assertions Preventing Sleep](mac/inspect-assertions-preventing-sleep.md)
 - [Keyboard Shortcuts For Interesting With Text Areas](mac/keyboard-shortcuts-for-interacting-with-text-areas.md)
 - [List All The Say Voices](mac/list-all-the-say-voices.md)
 - [Open Finder.app To Specific Directory](mac/open-finder-app-to-specific-directory.md)

mac/inspect-assertions-preventing-sleep.md

@@ -0,0 +1,41 @@
+# Inspect Assertions Preventing Sleep
+
+The `pmset` command is for inspecting and manipulating _Power Management
+Settings_ on MacOS. The `-g` flag is for _getting_ details. We can get a summary
+of power assertions with `-g assertions`. These assertions are ways that the
+system and display are prevented from sleeping.
+
+A common assertion preventing sleep is the user being active. Another example of
+an assertion is a program like `caffeinate` that sets a timeout preventing sleep
+for a fixed period of time.
+
+Here I activate a 30 minute (1600 second) `caffeinate` session and then I
+inspect the power management assertions which shows the details of that
+assertion as well as two others.
+
+```bash
+❯ caffeinate -t 1600 &
+[1] 98217
+
+❯ pmset -g assertions
+2025-11-02 13:20:57 -0600
+Assertion status system-wide:
+   BackgroundTask                 0
+   ApplePushServiceTask           0
+   UserIsActive                   1
+   PreventUserIdleDisplaySleep    0
+   PreventSystemSleep             0
+   ExternalMedia                  0
+   PreventUserIdleSystemSleep     1
+   NetworkClientActive            0
+Listed by owning process:
+   pid 98217(caffeinate): [0x00045477000194b3] 00:00:03 PreventUserIdleSystemSleep named: "caffeinate command-line tool"
+        Details: caffeinate asserting for 1600 secs
+        Localized=THE CAFFEINATE TOOL IS PREVENTING SLEEP.
+        Timeout will fire in 1597 secs Action=TimeoutActionRelease
+   pid 145(WindowServer): [0x00044f2f00099212] 00:00:00 UserIsActive named: "com.apple.iohideventsystem.queue.tickle serviceID:10009be9e service:AppleUserHIDEventService product:CTRL Keyboard eventType:3"
+        Timeout will fire in 600 secs Action=TimeoutActionRelease
+   pid 80(powerd): [0x00044f2f00019216] 00:22:34 PreventUserIdleSystemSleep named: "Powerd - Prevent sleep while display is on"
+```
+
+See `man pmset` and `man caffeinate` for more details.