Terminal guide
caffeinate: the macOS command to keep your Mac awake
macOS ships with a small command-line tool called caffeinate that stops your Mac from sleeping while something important is running — a build, a download, or a long AI coding session. It is built in, so there is nothing to install: open Terminal and it is already there at /usr/bin/caffeinate. This guide covers what every flag does, copyable examples you can paste straight into Terminal, and the limits worth knowing before you rely on it.
What caffeinate is
The caffeinate command creates a temporary sleep assertion — a request to macOS to hold off some kind of sleep. With no flags, it prevents idle sleep and holds that assertion until you stop it. Give it a utility to run and it holds the assertion only while that utility is running, then releases it automatically. That makes it a clean fit for wrapping a single command whose runtime you do not know in advance.
It requires no admin rights, writes nothing to disk, and adds no login item. When the command exits, the assertion is gone and your Mac returns to its normal power behavior.
Flag reference
You combine these single-letter flags to describe exactly which kind of sleep to block. They can be bundled, so -di is the same as -d -i.
| Flag | What it does |
|---|---|
-d | Prevent the display from sleeping (screen stays on). |
-i | Prevent the system from idle-sleeping. This is the default when you pass no flags at all. |
-m | Prevent the disk from idle-sleeping. |
-s | Prevent the system from sleeping entirely. This assertion is only valid while the Mac is on AC power — it is ignored on battery. |
-u | Declare that the user is active. If the display is off it turns it back on. Without -t it defaults to a 5-second timeout. |
-t <seconds> | Set a timeout in seconds after which the assertion is dropped. The timeout is ignored when you invoke a utility. |
-w <pid> | Wait for the process with the given PID to exit, then release the assertion. Ignored when you also invoke a utility. |
Copyable examples
Paste any of these into Terminal. Each is a complete command.
caffeinate -i bun run buildRun a build and keep the Mac awake for exactly as long as it takes — the assertion is released the moment the build finishes.
caffeinateWith no flags and no utility, prevent idle sleep until you press Control-C to stop it.
caffeinate -di -t 3600Keep both the display and the system awake, then automatically drop the assertion after 3600 seconds (one hour).
caffeinate -w 12345Hold the assertion until the process with PID 12345 exits — handy for babysitting a job started elsewhere.
caffeinate -s makePrevent full system sleep while a long job runs. Remember: -s only takes effect on AC power.
Gotchas and limits
caffeinate is a blunt instrument. A few things catch people out:
- No battery awareness. Apart from -s (which only works on AC), caffeinate will happily keep your Mac awake on battery and drain it flat. It has no notion of a safe battery threshold.
- Forgotten sessions. A bare caffeinate with no utility and no timeout runs until you kill it. It is easy to start one, walk away, and leave your Mac awake for days.
- The terminal must stay open. The assertion lives with the caffeinate process. Close that Terminal tab or window and the assertion dies with it. Logging out ends it too.
- No auto-detection. caffeinate cannot tell whether your agent is still working or finished ten minutes ago. You start and stop it by hand every time.
- -s is AC-only. The full system-sleep assertion is silently ignored on battery, so a script relying on it can still sleep when unplugged.
When a menu-bar app beats caffeinate
caffeinate is perfect for one-off commands you can see finish. But if you regularly run AI coding agents, the manual start/stop and the lack of battery smarts get old fast. That is the gap Perked fills. It is a native macOS menu-bar app that does the bookkeeping for you:
- Auto-detects agents. It recognizes 29 coding agents out of the box — Claude Code, Cursor and more — and keeps the Mac awake only while one is actually running.
- Power-aware rules. Stay awake only on AC power, or above a battery threshold you set, so you never drain the battery by accident.
- Timed sessions & Lock & Leave. Stay awake for a set duration, or lock the screen while the session keeps running.
- Sleeps again when done. No forgotten sessions, no terminal tab to babysit — it releases the Mac the moment the work is finished.
Stop babysitting the Terminal
One-time purchase, yours forever — €1 today, and your price is locked in for good.
Frequently asked questions
Is caffeinate built into macOS?
Yes. caffeinate ships with every modern macOS at /usr/bin/caffeinate — there is nothing to install. Open Terminal and run it.
Does caffeinate keep my Mac awake on battery?
The -i and -d assertions work on battery, but caffeinate has no battery awareness and will drain it. The -s system-sleep assertion is ignored unless you are on AC power.
How do I stop caffeinate?
Press Control-C in the terminal where it is running, or let it end on its own when the utility finishes, the PID exits, or the -t timeout elapses. Closing that terminal tab also stops it.
Can caffeinate detect when my AI agent starts and stops?
No. caffeinate is fully manual — you decide when to run it and when to stop. A menu-bar app like Perked watches for coding agents and keeps the Mac awake only while they are actually running.
Running long agent sessions? See how to keep your Mac awake for Claude Code, Cursor & AI agents.