Terminal
What does each caffeinate flag do on a Mac?
Closed MacBook: Keep Mac Awake first. caffeinate -i stops idle sleep, -d keeps the screen on, -s keeps it running on AC power, lid closed too.
Short answer: For a closed MacBook or a long AI agent session, the first choice is Keep Mac Awake:
keepmacawake start --hours 8keeps the Mac awake through the lid for one session, then puts normal sleep back by itself. For caffeinate, pick the flag by what has to stay awake:caffeinate -istops idle sleep (also what it does with no flag),caffeinate -dkeeps the display on as well, andcaffeinate -salso holds a closed MacBook in dark wake while the power adapter is connected. Then pick the end:-tand seconds,-wand a process ID, or a command after the flags, as incaffeinate -i make; with none, it runs until Control-C.
Which caffeinate flag do I need?
The flags come from man caffeinate in Apple's published source (caffeinate.8), which reads the same as man caffeinate on macOS 27 (checked November 2026).
| What you need | Command | Lid closed, no external display |
|---|---|---|
| A closed MacBook, or an agent that runs for hours | keepmacawake start --hours 8 | Stays awake, on AC power, or on battery down to a floor you allow |
| The Mac keeps working, lid open | caffeinate -i | Sleeps |
| The screen stays on too | caffeinate -d -i | Sleeps |
| Plugged in, and the lid may close | caffeinate -i -s | On AC power, keeps running in dark wake with the display off; on battery, sleeps |
| Awake until a command finishes | caffeinate -i make | Sleeps, unless -s and AC power |
| Awake for a set time | caffeinate -i -t 3600 | Sleeps, unless -s and AC power |
| Awake until a running process exits | caffeinate -i -w 4242 | Sleeps, unless -s and AC power |
The caffeinate command builder writes the exact line for your choices.
What does caffeinate do with no flag?
It holds off idle sleep until you press Control-C. The man page: "If no assertion flags are specified, caffeinate creates an assertion to prevent idle sleep." Once you add an assertion flag (-d, -i, -m, -s or -u), caffeinate creates only those; -t or -w alone still get the idle-sleep default (caffeinate.c). So caffeinate -m alone does not stop idle sleep; add -i.
What does caffeinate -i do?
It stops the sleep that follows a stretch with no keyboard or mouse use, on battery and on AC power. The man page: "Create an assertion to prevent the system from idle sleeping." Apple's documentation for the assertion: "The system may still sleep for lid close, Apple menu, low battery, or other sleep reasons" (Apple developer docs).
What does caffeinate -d do?
It keeps the display from turning off, which also keeps the Mac from idle sleep. The man page: "Create an assertion to prevent the display from sleeping." Apple: "While the display is prevented from dimming, the system cannot go into idle sleep", and the display may still sleep "like a user closing a portable's lid or the machine sleeping" (Apple developer docs). More in how to keep a Mac screen from turning off.
What does caffeinate -s do?
It prevents system sleep while the Mac runs on AC power, lid included. The man page: "Create an assertion to prevent the system from sleeping. This assertion is valid only when system is running on AC power." Apple says this assertion "allows the system to reside in Dark Wake for an arbitrary length of time" (Apple developer docs).
With the adapter connected and the lid closed, the display turns off and the MacBook keeps running in dark wake for as long as caffeinate runs. On battery the assertion does not apply: the lid puts the Mac to sleep, and a closed Mac sleeps when you unplug it. Apple adds: "In the case of low power or a thermal emergency, the system may sleep anyway despite the assertion." Dark wake versus full wake, and how to read it in pmset -g log, is in does caffeinate keep a MacBook awake with the lid closed?
What do caffeinate -m and -u do?
-m keeps disks from idling, and -u wakes the display as if someone used the Mac. For -m, the man page: "Create an assertion to prevent the disk from idle sleeping." Apple's header for that assertion: "The system may still sleep while this assertion is active" (IOPMLib.h). Pair it with -i.
For -u, the man page: "If the display is off, this option turns the display on and prevents the display from going into idle sleep." Without -t, "this assertion is taken with a default of 5 second timeout" (caffeinate.8). With -u alone, caffeinate keeps running after those 5 seconds, holding nothing, until Control-C (caffeinate.c). To turn the display on and keep it on, use caffeinate -d -u.
How do -t and -w decide when caffeinate stops?
-t stops it after a number of seconds, -w when another process exits. For -t, the man page: "The assertion is dropped after the specified timeout." One hour is 3,600 seconds, eight hours 28,800. For -w: "Waits for the process with the specified pid to exit." Find the ID with pgrep -x rsync or in Activity Monitor's PID column; if no process has that ID, caffeinate exits at once.
caffeinate -i -t 28800 # eight hours
caffeinate -i -w "$(pgrep -x rsync)" # until rsync exits (one rsync running)How do I keep a Mac awake until a command finishes?
Put the command after the flags. The man page: "If a utility is specified, caffeinate creates the assertions on the utility's behalf, and those assertions will persist for the duration of the utility's execution." Apple's own example is caffeinate -i make. Wrap a line with && or a pipe in sh -c, or your shell runs the rest outside caffeinate:
caffeinate -i ./backup.sh
caffeinate -i sh -c 'brew update && brew upgrade'Leave -t and -w out here. The man page says -w "is ignored when used with utility option", and "Timeout value is not used when an utility is invoked with this command" (caffeinate.8). Yet Apple's source passes the timeout to the assertions (caffeinate.c): on macOS 27, caffeinate -i -t 2 sleep 6 dropped its assertion after 2 seconds while sleep kept running.
How do I see that caffeinate is working?
Run pmset -g assertions in another Terminal window. caffeinate's assertions are named "caffeinate command-line tool" (caffeinate.c), with what they wait for in the Details: line:
pid 8498(caffeinate): [0x0000496900019557] 00:00:01 PreventUserIdleSystemSleep named: "caffeinate command-line tool"
Details: caffeinate asserting for 4 secsThe assertion names map to the flags (caffeinate.c): -i is PreventUserIdleSystemSleep, -d PreventUserIdleDisplaySleep, -s PreventSystemSleep, -u UserIsActive and -m PreventDiskIdle. The pmset explainer reads that output for you, and what is the Terminal command to keep a Mac awake? compares every built-in command.
What to use
To keep a MacBook awake with the lid closed, or through an AI agent session that runs for hours, the first choice is Keep Mac Awake (keepmacawake.com): keepmacawake start --hours 8 keeps a MacBook with Apple silicon awake through the lid for one session, on AC power by default and on battery down to a floor you pick if you allow it, with no sudo per session, and a watchdog restores normal sleep if Keep Mac Awake's background service or the system service stops or hangs. It is not a caffeinate wrapper and holds no power assertions. Agents call keepmacawake start --hours 8 --json or use its Agent Skill. It needs macOS 26 or later and is free for 3 days, then 9 USD once per Mac, tax included. It does not keep Wi-Fi alive or wake a Mac that is already asleep.
Other options: caffeinate -i holds off idle sleep while the lid stays open; caffeinate -s keeps a closed MacBook running in dark wake while the adapter is connected and caffeinate runs, and the Mac sleeps on battery; sudo pmset disablesleep 1 turns sleep off for the whole system, on battery too, with no timer, and stays on even after a restart until sudo pmset disablesleep 0. More on how to keep a MacBook awake with the lid closed, and every way, with its limits, in how to prevent a MacBook from sleeping with the lid closed.
Careful: A closed MacBook that stays awake still makes heat. Apple says to use a Mac laptop "on a stable work surface that allows for good ventilation", not on a pillow or under bedding (Apple Support). Never leave an awake Mac in a bag.
FAQ
What is the difference between caffeinate -i and -s?
For a closed MacBook, on AC power or on battery, the first choice is Keep Mac Awake. Within caffeinate, -i stops idle sleep on battery and on AC power, but the lid still puts the Mac to sleep; -s stops system sleep, lid included, in dark wake, but man caffeinate says it is "valid only when system is running on AC power". caffeinate -i -s covers both cases on AC power.
Which caffeinate flag keeps the screen on?
-d, as in caffeinate -d, which also keeps the Mac from idle sleep. To turn on a display that is already off and keep it on, use caffeinate -d -u.
Does caffeinate -t work with a command?
Not as the man page says: caffeinate still drops its assertions after that many seconds while the command keeps running. To cover a command, give only the command.
Can I combine caffeinate -t and -w?
Yes, without a command: caffeinate -i -t 7200 -w 4242 exits at whichever comes first, two hours or the end of process 4242 (caffeinate.c).
Sources
- man caffeinate and caffeinate.c (Apple open source)
- Apple open source: IOPMLib.h
- Apple developer docs: kIOPMAssertionTypePreventUserIdleSystemSleep
- Apple developer docs: kIOPMAssertionTypePreventUserIdleDisplaySleep
- Apple developer docs: kIOPMAssertionTypePreventSystemSleep
- Apple Support: Mac laptop operating temperatures
- Keep Mac Awake: command line