caffeinate on Mac: command examples, limits, and safer AI workflow options
caffeinate is the command-line tool built into macOS for keeping a Mac awake without touching System Settings. Running it with no flags blocks idle sleep until you press Ctrl-C; adding -t caps it to a fixed number of seconds, and wrapping a command lets it hold the Mac awake for exactly as long as that command runs. It does not touch closed-lid sleep, battery level, or heat — those need something else. Here are the real command examples, what caffeinate actually covers, and where a safety-aware tool like LidRun picks up the rest.
What the caffeinate command actually does
caffeinate is a small command-line utility that has shipped with macOS for years. It creates a power management assertion — a request to the system not to sleep — for as long as it runs, then releases that assertion automatically the moment it exits.
Used with no flags, caffeinate on its own blocks idle sleep until you stop it with Ctrl-C. Add -d to also keep the display from sleeping, or -m to keep disks from spinning down. These are separate, composable assertions, not one master switch.
The useful part for developers is that caffeinate has no GUI, no menu bar icon, and no configuration file. It is meant to be scripted — started, run, and released without touching a settings panel.
Basic caffeinate command examples
The simplest form is just caffeinate on its own, run in a terminal window you leave open — it blocks idle sleep until you press Ctrl-C or close the window.
For a fixed duration, caffeinate -t 3600 keeps the Mac awake for exactly one hour, then exits and releases the assertion on its own — no need to remember to stop it.
For a specific job, wrap the command directly: caffeinate -i npm run build keeps the Mac awake only while that build is running, and releases the moment the build finishes or fails. The same pattern works for caffeinate -i ./deploy.sh, a long rsync, or any other command with a clear start and end.
Where caffeinate works well, and where it falls short
For its actual job — blocking idle sleep during a script, a build, or a terminal session you're watching — caffeinate does exactly what it says, with no dependencies and no install step.
The limits show up around closed-lid work. caffeinate's assertions do not override the sleep macOS triggers when you close the lid — a MacBook still sleeps lid-closed with caffeinate running, unless it is in a true clamshell setup with an external display, keyboard, and power connected. It also has no concept of battery level or thermal state: it will hold a laptop awake all the way to a dead battery if you let it, with no way to notice a Mac running hot and back off.
It is also entirely manual. There is no detection of what is actually running — you have to remember to start it, and remember which flag you meant, every time.
Closed-lid limits and a safer AI/dev workflow
For an AI coding agent, a Docker build, or an Ollama model pull that needs to survive a closed lid or an unattended overnight run, caffeinate's gaps are exactly the ones that matter: no lid-closed handling, no battery floor, no thermal ceiling.
A safer pattern layers those guardrails on top of the same basic idea: keep the Mac awake only while real work is running, but auto-stop it if the battery drops too low or the chassis gets too hot, and release it automatically the moment the job actually finishes — not by relying on a person to remember.
This is where LidRun fits: it detects tools like Claude Code, Cursor, Docker, and Ollama automatically, supports closed-lid workflows the plain caffeinate command can't reach, and gates every session on battery and thermal thresholds instead of holding the Mac awake unconditionally.
A feature of the safe AI workload layer for Mac.
LidRun keeps your work running with the lid closed, with battery and thermal safety built in.
Frequently asked
No — caffeinate's power assertions don't override the sleep macOS triggers on lid-close. A MacBook still sleeps lid-closed with caffeinate running unless it's in a true clamshell setup with an external display, keyboard, and power connected.
Use the -t flag with a number of seconds, for example caffeinate -t 3600 for one hour. caffeinate exits and releases the assertion automatically once the time is up.
Yes — wrap the command directly, like caffeinate -i npm run build. The Mac stays awake only while that command runs, and the assertion releases the moment it exits.
For short, watched terminal sessions, caffeinate is enough. For closed-lid or unattended AI/dev runs, LidRun adds automatic tool detection, closed-lid support, and battery/thermal auto-stop on top of the same basic idea.