The Mac caffeinate Command: Complete Guide for Developers

Every macOS installation includes caffeinate, a built-in Terminal command that prevents your Mac from sleeping. It ships with every version of macOS and requires no installation, no admin privileges, and no third-party software. For developers running long builds, downloads, or processes that need to complete without interruption, it’s the simplest first line of defense against unwanted sleep.

This guide covers every caffeinate flag, practical usage patterns for developers, where the command falls short, and when you need something more capable.

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 Energy Saver 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. According to Apple’s developer documentation, power assertions are the sanctioned mechanism for preventing sleep, and caffeinate is the official command-line interface to that system (Apple Developer Documentation, “Managing Power Assertions”).

What flags does caffeinate support?

Caffeinate supports five primary flags that control which type of sleep to prevent: -d for display sleep, -i for idle sleep, -s for system sleep on AC power, -u to assert user activity, and -t to set a timeout in seconds. Each flag targets a different sleep trigger, and you can combine them for precise control over your Mac’s power behavior.

Here’s the complete flag reference:

Flag	Prevents	Use Case	Example
-d	Display sleep	Keep screen visible during monitoring	caffeinate -d
-i	Idle sleep	Background processes keep running	caffeinate -i
-s	System sleep (AC power)	Prevent sleep while plugged in	caffeinate -s
-u	Declares user activity	Reset idle timer once	caffeinate -u -t 1
-t N	(timeout)	Auto-stop after N seconds	caffeinate -t 3600
(no flags)	Idle sleep (default)	General prevention	caffeinate

The -d flag is the most visible. It keeps your display illuminated regardless of the Energy Saver display sleep setting. 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 -s flag only works when your Mac is connected to AC power. It prevents system-level sleep that goes beyond idle sleep — the kind that can be triggered by scheduled sleep times or closing the lid on some configurations. On battery power, this flag has no effect (macOS prioritizes battery preservation).

The -u flag is unique: it declares that user activity is happening right now, which resets the idle timer. It’s a one-shot assertion rather than a continuous one. It’s most useful in scripts that need to periodically poke the system to prevent idle sleep without creating a continuous assertion.

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. Always use -t when you can estimate the duration — forgetting to stop caffeinate means your Mac never sleeps, draining battery.

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 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/

Downloads that take more than your idle sleep timeout (typically 10-15 minutes) will fail 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:

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

Creates a detached tmux session running your build, with caffeinate preventing sleep for the duration. Even if you close your terminal, the tmux session and the caffeinate assertion persist.

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

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

This keeps the Mac awake for up to two hours starting at 2 AM while the backup runs. Note that 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.

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 clamshell sleep, which caffeinate generally cannot override unless you have an external display, keyboard, and mouse connected. This is a hardware-level behavior that software assertions don’t control.

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 — GUI tools provide a more complete solution. FavTray’s Move Mouse feature generates actual mouse movement events that keep both the system awake and applications reporting active status, all from your menu bar with no Terminal window required.

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
All-day sleep prevention during WFH	FavTray	Persistent, no terminal needed
Keeping Slack/Teams active	FavTray Move Mouse	Simulates input, not just sleep prevention
Nightly backup script	caffeinate -t	Set-and-forget with timeout
Presentation or demo	caffeinate -d -t	Display stays on for fixed time
Multiple tools active during meetings	FavTray	Mouse movement keeps all apps active

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.

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.