CLI reference

Generated from guaranate --experimental-dump-help for guaranate 0.2.0, so every documented flag and short alias matches the shipped binary.

guaranate

A developer-friendly macOS keep-awake CLI.

Keep your Mac awake when work needs to finish. Give your Mac some guaraná.

guaranate 2h                  stay awake for two hours
guaranate                     stay awake until interrupted
guaranate --watch 4821        stay awake until pid 4821 exits
guaranate while npm test      stay awake for exactly one command

The timed form is the default command: see guaranate run --help for its full options, and guaranate while --help for the command form.

guaranate [<duration>] [--display] [--system] [--reason <text>] [--version]
guaranate --watch <pid> [--display] [--system] [--reason <text>] [--version]
guaranate while [--display] [--system] [--reason <text>] <command> [<arguments> ...]

Option	Description	Default
-h, --help	Show help information.	—

guaranate run (default)

Stay awake for a duration, until interrupted, or until a process exits.

This is the default command, so its name is optional: guaranate 2h and guaranate run 2h do the same thing.

guaranate 2h              stay awake for two hours
guaranate                 stay awake until interrupted
guaranate --watch 4821    stay awake until pid 4821 exits

A watched process is not started, stopped, or otherwise touched by guaranate — only observed. Ctrl+C detaches and leaves it running. Processes belonging to another user can be watched too.

guaranate run [<duration>] [--watch <pid>] [--display] [--system] [--reason <text>] [--version] [--help]

Argument	Description
<duration> (optional)	How long to stay awake: 30m, 2h, 1h30m, 90s, or a plain number of seconds. Omit to stay awake until interrupted.

Option	Description	Default
-w, --watch <pid>	Stay awake until the process with this pid exits.	—
-d, --display	Also keep the display awake (default lets the display sleep).	—
-s, --system	Prevent all system sleep.	—
-r, --reason <text>	Reason recorded on the power assertion.	—
-v, --version	Show the version.	—
-h, --help	Show help information.	—

guaranate while

Stay awake for exactly as long as a command runs.

The command gets this terminal and a process group of its own: its output and input pass straight through, Ctrl+C and Ctrl+Z reach it exactly as they would without guaranate in front, and guaranate exits with the command’s own exit code — or 128 + signal number if it is killed by a signal. Stdout carries only the command’s output; guaranate’s own lines go to stderr.

Guaranate’s own flags belong before the command. Everything from the first non-flag token onwards is handed to the command untouched; a leading token that looks like a flag is reported rather than run, so use -- when the command’s own name or first argument could be mistaken for one of ours:

guaranate while npm test
guaranate while --display -- ./build.sh --release

guaranate while [--display] [--system] [--reason <text>] [--help] <command> ...

Argument	Description
<command>	The command to run, with its arguments.

Option	Description	Default
-d, --display	Also keep the display awake (default lets the display sleep).	—
-s, --system	Prevent all system sleep.	—
-r, --reason <text>	Reason recorded on the power assertion.	—
-h, --help	Show help information.	—