Keep awake
Holds the Mac (and optionally the display) awake for a time, until a time, or while a condition stays true, and lets go on its own.
Keep the Mac awake for for
Details #
Holds the Mac awake the way Amphetamine and Caffeine do: a power assertion that stops the Mac sleeping when it is idle. The step returns at once. The hold lives in the Engine, not in the run, so the run finishes and its trace says what is being held, for example "Holding awake: while Final Cut Pro is running".
start (the default) begins a hold. With none of
for,untilorwhile, it lasts until astop.stop ends the hold. It is not an error when there is nothing to stop.
toggle stops the hold if this macro has one, and starts one if not. Bind it to a key and pressing it again stops it.
There is one hold per id, and the default id is the macro, so a toggle macro stops its own hold and never someone else's. Starting again with the same id replaces the hold.
for, until and while can be combined: the hold ends at the first of them. A while list holds only while every condition is true, and ends the first time one is false. The Engine looks again every 30 seconds, and straight away when an app launches or quits, the power source or displays change, or a watched file changes.
Display. With display on, the display stays on too; otherwise only the Mac itself stays awake and the display can still sleep.
Battery floor. Every hold ends when the Mac is on battery below the floor (20% unless you change it in Settings › Awake: 10 to 50%, or off). The Engine shows "Stopped keeping awake: battery at 19%".
Seeing holds. While any hold is live the menu bar glyph gets a small cup and the menu lists each one ("Awake until 17:30 · Final Cut Pro") with Stop. In the palette, type "awake" to see them and to start "Keep awake for…" 15 minutes, 1 hour, 3 hours or until you stop. switchboard state lists them under awake, and pmset -g assertions shows each as "Switchboard: <macro name>".
Quit Switchboard from the menu ends every hold, and says so first when one is live. Pausing the Engine does not end them. Holds do not survive a restart of the Engine: the assertion belongs to the process, so a crash can never leave the Mac held.
Parameters #
| Parameter | Type | Required | Values | What it does |
|---|---|---|---|---|
action | one of | start stop toggle | start (default), stop or toggle. | |
display | yes / no | Keep the display awake too. Default off. | ||
for | any value | How long to hold: 30m, 2h, 1 hour, 45 minutes or a number of seconds. | ||
id | text | Names the hold. Default: this macro. | ||
until | text | A time to hold until, such as 17:30 (the next one) or a date. | ||
while | list of condition | A list of conditions that must all stay true. A condition that cannot be watched, such as the AI condition, is refused. |
Every step also accepts label, onFailure, timeout and dryRunSafe.
Examples #
- FinalCut launches
- Keep the Mac awake while FinalCut is running
- A file is created in ~/Downloads matching “*.crdownload”
- Keep the Mac awake while a file exists at {{triggerValue}}
- Press ✦A
- Toggle keeping the Mac awake for 1h
- 2 displays are connected becomes true
- Keep the Mac awake while 2 displays are connected and the Mac is charging
Gotchas #
Closing the lid still sleeps a laptop on battery without an external display: macOS only allows that for a root helper, and Switchboard does not offer it.
There is no mouse jiggling. A power assertion is the honest way to keep the Mac up, and it is what Activity Monitor and
pmset -g assertionsshow. Some company idle-lock policies ignore it.In a dry run the step only notes what it would hold.
If a
whilecondition is already false when the step runs, nothing is held, and the note says so.
See also #
Sleep, restart or log out, Wait until a condition holds, App running, Battery