Why caffeinate does not work with the lid closed.

caffeinate keeps a Mac awake when ordinary inactivity would make it sleep. Closing a MacBook lid is not ordinary inactivity. It is a separate hardware-triggered sleep path, so a busy command and an idle-sleep assertion can both be active while the Mac still goes to sleep as soon as the lid shuts.

What caffeinate actually promises

The macOS manual says that running caffeinate with no flags creates an assertion that prevents idle system sleep. The assertion lasts until the process exits. That is useful for a build, download, presentation, or terminal job when the lid stays open.

caffeinate -i make
caffeinate -i -w 12345
caffeinate -i -t 3600

The first command keeps idle sleep away while make runs. The second follows a process ID. The third expires after one hour. None of them changes what macOS does when it detects a closed lid.

The flags do not mean closed-lid mode

• -i prevents idle system sleep. This is the default assertion and does not override lid-close sleep.
• -s requests prevention of system sleep and is valid only on AC power. It still does not configure a MacBook for closed-display operation.
• -d prevents idle display sleep. That is the opposite of the usual lid-closed goal, where the screen should turn off.
• -m prevents idle disk sleep. It does not affect the lid.
• -u declares user activity and can wake the display. It is not a lid override.

How to see the assertion

While caffeinate is running, open another Terminal window and inspect the system-wide assertions:

pmset -g assertions

You will normally see PreventUserIdleSystemSleep or another assertion owned by caffeinate. This confirms that the command is working. It also explains the limitation: power assertions describe kinds of sleep that software would like to avoid, while the lid switch has its own policy.

What works instead

Apple's supported closed-display setup uses an external display, power, and external input devices. An HDMI dummy plug can imitate the display. The command sudo pmset -a disablesleep 1 is another workaround, but it is an undocumented, system-wide, admin-level switch that must be undone manually. A purpose-built app can change only the lid-close behavior for the session and keep the state visible.

The practical rule

Use caffeinate when the Mac stays open and you want a command to survive idle timers. Use a closed-display solution when the physical lid will close. For a full comparison, read clamshell mode without an external display. For coding sessions, see keeping Claude Code, Codex, and other agents running.

Method: checked against the macOS caffeinate(8) and pmset(1) manuals and verified with pmset -g assertions on an Apple Silicon MacBook.