Why caffeinate doesn’t work with the lid closed
caffeinate is the first thing everyone tries, and on a desk it’s perfect. Close a MacBook on battery, though, and it goes to sleep anyway. Here’s what each flag does and why the lid wins.
Short answer. caffeinate holds power assertions against idle sleep. Closing the lid is a different trigger. The only flag that blocks system sleep, -s, works only on AC power, and even then a MacBook without an external display sleeps when you close it.
What the flags do
From the caffeinate manual:
| Flag | What it prevents | With the lid closed on battery |
|---|---|---|
-i | Idle sleep of the system | Doesn’t help |
-d | Display sleep | Doesn’t help (the display is off anyway) |
-s | System sleep, “valid only when system is running on AC power” | Ignored on battery |
-u | Declares the user active (wakes the display) | Doesn’t help |
-t 3600 | Sets a timeout in seconds | — |
-w PID | Holds until that process exits | — |
Why the lid wins
Every one of those flags creates a power assertion: a note to macOS saying “don’t sleep yet”. You can see the ones active right now with:
pmset -g assertions
Idle sleep respects them. Lid sleep, called clamshell sleep, is a separate path: when a MacBook’s lid closes and there is no external display on power, macOS sleeps regardless. macOS does have assertion types meant to apply when the lid is closed, but in tests on a MacBook Air they were refused to a normal user (“not authorized”). That’s why the free tools that do work with the lid closed either need your password or use a different system call.
What caffeinate is great for
Lid open, especially plugged in, it’s the best tool there is: built in, nothing to install, and it ends by itself.
caffeinate -i make release # awake while the command runs
caffeinate -i -w 4242 # awake until process 4242 exits
caffeinate -i -t 5400 # awake for 90 minutes
caffeinate -dims # keep everything awake (AC power) until Ctrl-C
What to use when the lid must close
- At a desk: Apple’s closed-display mode, with power, an external display and a keyboard.
- On battery, in a bag:
sudo pmset -a disablesleep 1, which you must remember to undo (how), or a menu bar app that does it for you and undoes it at the end, such as Amphetamine, Clamshell, Vigil or Hibernot. All four options are compared in how to keep a MacBook awake with the lid closed.
If you’re doing this for Claude Code or Codex, the rest of the checklist (network, permissions, heat) is in run Codex or Claude Code overnight on a MacBook.