Keep your Mac awake from the command line

Keepresso ships a small command-line tool so you can control it from the terminal, a shell script, a Makefile, or a CI job, without reaching for the menu bar. The command is keepresso, and it works two ways: it can talk to the menu-bar app, or it can hold the Mac awake on its own like the built-in caffeinate.

Install the command

If you installed Keepresso with Homebrew, the keepresso command is already on your PATH, nothing to do:

brew install --cask gyorgysh/keepresso/keepresso

If you installed the app from the DMG instead, the tool sits inside the app bundle and your PATH does not know about it yet. Link it once:

sudo ln -s /Applications/Keepresso.app/Contents/Helpers/keepresso /usr/local/bin/keepresso

Check it is wired up:

keepresso version

Control the app

These commands are delivered to the Keepresso app, launching it if it is not already running. They are the scriptable twin of the menu.

keepresso start                 # start an open-ended session
keepresso start --for 90        # start a 90 minute session
keepresso start --until 18:00   # run until a wall-clock time
keepresso stop                  # end the current session
keepresso toggle                # flip it on or off

So a long job can wake the Mac when it begins and let it sleep when it finishes:

keepresso start
make release
keepresso stop

Read the status

keepresso status tells you whether a session is running, and its exit code makes it easy to branch on in a script:

• 0 the Mac is being kept awake
• 1 it is not
• 2 the app is not running

keepresso status && echo "awake" || echo "asleep"

Add --json for a machine-readable answer:

keepresso status --json

The same session state is also mirrored to a file, so a menu-bar tool, a status line, or a widget can read it without launching anything:

~/Library/Application Support/Keepresso/status.json

It carries the current state and ISO 8601 timestamps.

Standalone holds, no app needed

Sometimes you do not want to involve the app at all, you just want this one shell to keep the Mac awake, exactly like caffeinate. In this mode the keepresso process itself holds the power assertion, and the Mac is free to sleep again the moment it exits.

keepresso -i            # hold until you press Ctrl-C
keepresso -t 3600       # hold for a number of seconds
keepresso -w 5123       # hold until process 5123 exits
keepresso -d            # also keep the display awake (combine with the above)
keepresso -u            # declare user activity: wake the display now

The most useful pattern is tying wakefulness to the life of a command or a shell:

keepresso -w $$ &       # stay awake as long as this shell lives

ffmpeg -i in.mov out.mp4 & keepresso -w $!   # hold until the encode finishes

Because these holds are real macOS power assertions, they show up in pmset -g assertions and in Keepresso's own Activity pane, right alongside every other app holding the Mac up.

Automation leases, for scripts and agents

A start with no stop can pin the Mac awake forever if the script crashes. For unattended automation, take a lease instead: a bounded grant with a time limit the owner must keep renewing. If the tool dies, the lease expires and the Mac can sleep again.

ID=$(uuidgen)
keepresso lease acquire --id "$ID" --tool my-script --task "nightly render" --ttl 600
keepresso lease heartbeat --id "$ID"   # renew before half the TTL elapses, on a loop
keepresso lease release --id "$ID"     # done, let the Mac rest
keepresso lease list --json            # every live lease, machine-readable

Live leases show in the menu with countdowns, Keepresso unions them all, and a maximum lifetime (capped at 7 days) is a ceiling heartbeats cannot extend. The full protocol, the MCP server, and the one-click agent skill are covered in let AI agents keep your Mac awake.

Wake schedule

The CLI can also read the system's scheduled wakes, and, with your permission, change them:

keepresso wake status                          # read the schedule, always allowed
keepresso wake set --at "2026-07-24 07:30"     # one-shot wake
keepresso wake set --repeat MTWRF --time 07:30 # repeating wake
keepresso wake clear

status works for anyone. set and clear apply a system-wide change through the administrator helper, so they work only while Allow automation to change the wake schedule is on under Preferences, Automation. It is off by default.

Related

• Control Keepresso from Shortcuts, Raycast, or a script covers the Shortcuts actions and the keepresso:// URL scheme for no-terminal automation.
• Keepresso vs Amphetamine, KeepingYouAwake, and caffeinate explains how Keepresso relates to the built-in caffeinate command.