Guaranate

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

guaranate — zsh

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

             🌿 Guaranate

  ▏██████████████████▎░░░░░░░░░▕   65%

  Elapsed       · · · · · · · 01:18:00
  Remaining     · · · · · · · 00:42:00
  Ends          · · · · · · · 23:12:07
  Assertion     · · · · · System sleep
  Display       · · · · · ·  May sleep

Press Ctrl+C or q to stop

Human durations

30m, 2h, 1h30m, 90s, 1d2h — or a bare number of seconds. No -t 7200 arithmetic.

Native, not a wrapper

Talks to IOKit IOPMAssertion* directly. /usr/bin/caffeinate is never invoked.

Never leaves a stale assertion

Expiry, q, Ctrl+C, and SIGTERM all release the assertion before the process exits.

Readable while it runs

A live progress frame on a TTY; one start line and a short completion summary when output is piped.

Where to next

Keeping your Mac awakeDuration syntax, indefinite sessions, assertion modes, exit codes, and the live frame.

Tying a session to a processguaranate while , watching a running pid, exit codes, and signal behaviour.

InstallHomebrew, a release binary with checksum, or a build from source.

How it worksIOKit power assertions, verifying a live session with pmset, and the cleanup guarantee.

CLI referenceEvery command, flag, and short alias — generated from the binary's own help output.

Guaranate is a small macOS command-line utility for managing sleep-prevention sessions. The name is a play on guaraná, the Brazilian stimulant, and Apple’s caffeinate command.