macOS caffeinate Man Page: All 7 Flags Explained

Short answer: caffeinate is Apple’s built-in command that stops a Mac from sleeping, and its man page documents seven flags. Run caffeinate (Ctrl+C to stop), caffeinate -d to keep the screen on, caffeinate -t 3600 for one hour, or caffeinate -i npm run build to stay awake only while a command runs.

TL;DR

• No flags means -i: caffeinate blocks idle sleep and still lets the screen turn off.
• -d keeps the display on.
• -s only works on AC power. On battery it does nothing.
• Wrapping a command ties the assertion to it: it lasts as long as the command runs, and -w is ignored. The man page says -t is ignored too, but on macOS 26.6 it still ends the assertion after N seconds, so leave it off.
• caffeinate can’t keep a closed MacBook awake. Closing the lid is a separate sleep trigger that no caffeinate flag is documented to block.

It ships with every Mac and needs no installation, no admin privileges, and no third-party software. This guide translates the caffeinate man page into plain English, then covers practical patterns for builds and AI agents, how to check it is working, and where the command falls short.

What does the caffeinate command actually do?

The caffeinate command creates a power management assertion that tells macOS not to enter sleep mode. It overrides your sleep settings for as long as the command is running, preventing idle sleep, display sleep, or system sleep depending on which flags you use. When the command exits — either by timeout, Ctrl+C, or the completion of a wrapped process — macOS resumes its normal sleep behavior immediately.

Under the hood, caffeinate uses the same IOPMAssertionCreateWithName API that applications like Xcode and Safari use to prevent sleep during active tasks. The difference is that caffeinate exposes this capability through the command line, giving you fine-grained control without writing any code.

The command has been part of macOS since OS X 10.8 Mountain Lion (2012), making it available on every Mac you’re likely to encounter in a professional setting. Its man page (man caffeinate) describes it in one line: “prevent the system from sleeping on behalf of a utility.”

caffeinate man page: all 7 flags

The caffeinate man page lists seven flags. Five choose which kind of sleep to block (-d, -i, -m, -s, -u) and two control how long the assertion lasts (-t, -w). With no flags at all, caffeinate prevents idle sleep. You can combine flags, for example caffeinate -dims.

Flag	What the man page says it does	Use case	Example
-d	Prevents the display from sleeping	Keep the screen visible while monitoring	caffeinate -d
-i	Prevents the system from idle sleeping (the default with no flags)	Background jobs keep running	caffeinate -i
-m	Prevents the disk from idle sleeping	Long reads/writes to a spinning disk	caffeinate -m
-s	Prevents the system from sleeping; valid only on AC power	Stay awake while plugged in	caffeinate -s
-u	Declares that the user is active: turns the display on if it’s off and keeps it from idle sleep. Defaults to a 5-second timeout if no -t is given	Wake the screen from a script	caffeinate -u -t 60
-t N	Drops the assertion after N seconds. “Not used” when caffeinate runs a command (in practice it still applies: see below)	Auto-stop after a fixed time	caffeinate -t 3600
-w PID	Waits for process PID to exit, then releases the assertion. Ignored when caffeinate runs a command	Stay awake until a running job ends	caffeinate -w 12345

The -d flag is the most visible. It keeps your display on regardless of the “Turn display off” setting in Lock Screen. Without it, your screen may turn off while the system stays awake. Use this when you need to see output — monitoring build progress, watching log tails, or running a presentation from Terminal.

The -i flag is the most commonly needed for developers. It prevents idle-triggered sleep while allowing the display to dim and turn off normally. Your long-running build completes in the background even if the screen goes dark. This is the best flag for “just don’t sleep while this runs.”

The -m flag keeps disks from idle sleeping. On Macs with internal SSDs it rarely matters; it is for external spinning drives that spin down mid-job.

The -s flag is the strongest assertion, but the man page says it is valid only when the Mac runs on AC power. On battery, it has no effect, so pair it with -i if the Mac might be unplugged.

The -u flag is different from the others: it declares that a user is active right now. If the display is off, it turns it on and keeps it from idle sleep. Without -t, the assertion lasts only 5 seconds, so scripts use it to wake the screen, not to hold the Mac awake.

The -t flag adds a timeout in seconds. Without it, caffeinate runs until manually stopped. caffeinate -t 7200 keeps your Mac awake for exactly two hours and then exits cleanly. Use -t when you can estimate the duration — forgetting to stop caffeinate means your Mac never sleeps, draining battery. The man page says the timeout is not used when caffeinate wraps a command, but that is out of date: on macOS 26.6.2, caffeinate -i -t 60 make drops the assertion after a minute even if make is still running. When you wrap a command, leave -t off.

The -w flag ties the assertion to a process that is already running. caffeinate -i -w 12345 stays awake until PID 12345 exits. Unlike -t, it really is ignored when caffeinate wraps a command.

What are the most useful caffeinate patterns for developers?

The most practical pattern for developers is wrapping a command with caffeinate so sleep prevention starts and stops automatically: caffeinate -i npm run build keeps the system awake during the build and releases immediately when it finishes. This eliminates the most common problem — forgetting to cancel caffeinate after the task completes.

Here are the patterns you’ll use most often:

Keep awake during a build:

caffeinate -i npm run build
caffeinate -i cargo build --release
caffeinate -i xcodebuild -scheme MyApp -configuration Release

The -i flag prevents idle sleep while the build runs. When the build command exits (success or failure), caffeinate exits automatically. No cleanup needed.

Keep awake while an AI coding agent works:

caffeinate -i claude       # Claude Code: awake until you exit the session
caffeinate -i codex        # the same for OpenAI's Codex CLI
caffeinate -i -w 48213     # an agent that is already running (find its PID with pgrep -f)

Agent runs that take 20 minutes or more are exactly where idle sleep bites: the Mac sleeps, the network drops, and the run stalls. Wrapping the CLI holds the assertion for the whole session. Add -d if you want to keep watching the output.

Keep awake with display on for a fixed duration:

caffeinate -d -t 3600

Keeps the screen on for one hour. Useful during presentations, demos, or when monitoring a dashboard. The timeout ensures it doesn’t run forever if you forget.

Keep awake during a large download:

caffeinate -i curl -O https://example.com/large-dataset.tar.gz
caffeinate -i wget -r https://example.com/docs/

A download that outlasts your sleep timer will stall if your Mac sleeps mid-transfer. Wrapping with caffeinate prevents this.

Keep awake during SSH sessions:

caffeinate -i ssh user@server 'long-running-script.sh'

Prevents your local Mac from sleeping while a remote command executes over SSH. If your Mac sleeps, the SSH connection can drop and the remote process may be interrupted (unless you’re using tmux or screen on the remote side).

Background caffeinate with PID tracking:

caffeinate -i -w $$ &

This starts caffeinate in the background and ties it to the current shell’s process ID ($$). When you close the terminal window, caffeinate exits automatically. Useful when you want to keep working in the same terminal.

How do you combine caffeinate with other command-line tools?

Caffeinate integrates seamlessly with standard Unix patterns — piping, backgrounding, and process substitution all work as expected. The key technique is using caffeinate as a wrapper around the command you want to protect, rather than running it separately in another window.

With tmux or screen sessions:

tmux new-session -d -s build 'caffeinate -i make all'

Put caffeinate inside the session. tmux new-session -d returns as soon as the session starts, so wrapping tmux itself (caffeinate -i tmux new-session -d …) would release the assertion almost immediately. With caffeinate inside, the assertion lasts as long as the build, even if you close your terminal.

With cron or launchd: If you have scheduled tasks that need the system awake, prefix the command in your crontab:

0 2 * * * caffeinate -i /path/to/nightly-backup.sh

This keeps the Mac awake for as long as the backup script runs, starting at 2 AM. Don’t add -t here: it would end the assertion after that many seconds even if the backup is still running. This only works if the Mac is already awake at 2 AM — caffeinate cannot wake a sleeping Mac.

Chained commands:

caffeinate -i bash -c 'npm install && npm run build && npm run test'

The entire chain runs under caffeinate’s protection. If any command fails and the chain stops, caffeinate exits.

How do you check that caffeinate is working?

Open a second Terminal window and run:

pmset -g assertions | grep caffeinate

While caffeinate is running, you will see a line like this for its PID:

pid 69528(caffeinate): [0x000102db0001869a] 00:00:00 PreventUserIdleSystemSleep named: "caffeinate command-line tool"

PreventUserIdleSystemSleep is the -i assertion; -d shows up as PreventUserIdleDisplaySleep. If nothing prints, caffeinate has already exited. Run pmset -g assertions without the grep to see every app holding your Mac awake.

Why isn’t caffeinate working?

When caffeinate seems to do nothing, the cause is almost always one of four things: -s on battery, a -t timeout on a wrapped command, a caffeinate process that has already ended, or a closed lid. Check first with:

pmset -g assertions | grep -A3 caffeinate

A working -i (or no-flag) run shows PreventUserIdleSystemSleep, and -d shows PreventUserIdleDisplaySleep. A wrapped command adds Details: caffeinate asserting on behalf of '/path/to/command', and a Timeout will fire in N secs line means a -t countdown is running. No caffeinate line means no assertion.

You used -s on battery. The man page says the -s assertion “is valid only when system is running on AC power”. Unplugged, it does nothing and the Mac idle-sleeps as normal. Use caffeinate -is so the -i assertion covers you on battery.

You added -t or -w to a wrapped command. -w is ignored when caffeinate runs a command. -t is not, despite the man page: caffeinate -i -t 600 ./long-job.sh releases the assertion after 10 minutes even if the job is still running, while caffeinate itself stays in the process list, so it looks as if it is still working. Apple’s caffeinate source passes the timeout to every assertion it creates. Drop -t and let the command decide how long.

caffeinate has already ended. The assertion lasts only as long as the process. Ctrl+C, killall caffeinate, quitting Terminal or closing its window (which sends a hangup signal) all release it, and a wrapped command that exits early takes caffeinate with it. To outlive the window, run it inside tmux as shown above.

The lid is closed. Closing a MacBook’s lid is a separate sleep trigger. Apple’s IOKit header says that with the idle-sleep assertion caffeinate creates, “the system may still sleep for lid close”, and no caffeinate flag is documented to change that. For clamshell mode and the pmset option, see keeping a Mac awake with the lid closed.

Have the opposite problem, a Mac that won’t sleep? A forgotten caffeinate in an old tab is a common cause: see what’s keeping your Mac awake.

caffeinate vs Amphetamine

caffeinate is a Terminal command with no interface; Amphetamine is a free Mac App Store menu bar app built on the same power assertions. Amphetamine adds sessions you start with a click, automatic triggers (Wi-Fi network, running app, external display and more), a Closed-Display Mode for keeping a MacBook awake with the lid closed, and optional cursor movement. Use caffeinate to protect one job; use Amphetamine if you want a toggle or need the lid closed.

For the full picture, see our keep-alive app comparison and FavTray vs Amphetamine.

What can’t caffeinate do?

Caffeinate cannot simulate user activity for applications that track mouse or keyboard input, cannot wake a Mac from sleep, cannot prevent sleep when the lid is closed on most configurations, and cannot keep collaboration tools like Slack or Microsoft Teams showing you as “active.” These limitations represent the boundary between power management and input simulation.

Specific limitations developers hit in practice:

No Slack/Teams active status. These applications detect user input events (mouse movement, keystrokes), not system sleep state. A Mac that’s awake but idle will still show you as “Away” after a few minutes. Caffeinate keeps the system running but doesn’t generate the input events that these apps look for.

No lid-closed operation on most Macs. Closing the lid on a MacBook triggers sleep, and Apple’s IOKit documentation says the idle-sleep assertion caffeinate creates does not stop that. The exception is clamshell mode, where the MacBook is on power with an external display, keyboard and mouse connected.

No waking from sleep. Caffeinate is preventive, not curative. It stops sleep from happening while it’s running, but it can’t wake a Mac that’s already asleep. For scheduled wake, you need pmset schedule wake or Power Nap settings.

No persistent state. Caffeinate runs as a process. If Terminal crashes, if you restart your Mac, or if you accidentally close the window, the assertion disappears immediately. There’s no daemon mode or auto-restart capability.

For developers who need to go beyond what caffeinate offers — keeping collaboration tools active, persisting across restarts, or preventing sleep without an open terminal — our guide to the ways to keep a Mac awake compares the GUI options. FavTray’s Keep Alive holds a sleep assertion and moves the cursor slightly, so apps keep reporting you as active, all from the menu bar with no Terminal window required. It is free for 3 hours of running time a day, and FavTray’s one-time Lifetime licence (pricing) removes the limit.

When should you use caffeinate versus a GUI tool?

Use caffeinate for one-off, command-specific sleep prevention — builds, downloads, and scripts where you want automatic cleanup when the command finishes. Use a GUI tool like FavTray when you need persistent sleep prevention throughout your workday, application-level active status, or a quick toggle without opening Terminal.

Decision matrix:

Scenario	Best Tool	Why
Preventing sleep during a specific build	caffeinate -i	Auto-exits when build completes
Long AI agent session	caffeinate -i claude (or codex)	Awake for exactly the session
All-day sleep prevention during WFH	A menu bar keep-awake app	Persistent, no terminal needed
Keeping Slack/Teams active	FavTray Keep Alive	Simulates input, not just sleep prevention
Nightly backup script	caffeinate -i script	Releases when the script ends
Presentation or demo	caffeinate -d -t	Display stays on for fixed time
Lid closed, no external display	Amphetamine	Closed-Display Mode

The caffeinate command is a precision tool: it does one thing well and gets out of the way. For developers comfortable with the terminal, it’s the right choice for protecting individual processes. But for the increasingly common scenario of keeping a Mac active throughout an 8-hour workday — preventing sleep, keeping the display on during idle moments, maintaining active status in collaboration tools — a dedicated menu bar app is more practical than leaving a caffeinate process running in a terminal window you might accidentally close. If you are weighing a hardware or software mouse jiggler instead, read what IT can see first.

Both approaches have their place. The best workflow uses caffeinate for command-specific protection (wrapping builds and long-running scripts) and a GUI tool for ambient, always-on sleep prevention during working hours.

Sources (checked 30 September 2026): man caffeinate on macOS 26.6.2; Apple’s caffeinate source and IOPMLib.h; pmset -g assertions output captured on a MacBook running macOS 26.6.2.