Docs — Coffeetosh CLI Reference

Step 1

Installation

There are two ways to get Coffeetosh. Download the Mac app directly and enable CLI access from inside the app, or install via Homebrew if you prefer terminal-first setup.

Download & install the app

Grab the latest .dmg from GitHub Releases or via Homebrew. Requires macOS 13 Ventura or later.

zsh

$ brew install coffeetosh

Enable CLI from inside the app

Open the Coffeetosh menu bar icon → Settings → click Install CLI Tool. This creates a symlink at /usr/local/bin/coffeetosh. You can also run it from the terminal directly:

zsh

$ coffeetosh install-cli

Verify it works

Run coffeetosh status to confirm the CLI is installed correctly.

zsh

$ coffeetosh status
Coffeetosh: INACTIVE

Core Concept

Two Operating Modes

Coffeetosh has two modes for preventing sleep. Choose based on your use case.

Lid Closed

--mode coffeetosh (default)

Prevents sleep when the lid is physically closed. Ideal for headless servers, SSH workflows, and overnight tasks. Uses pmset to disable sleep assertions at the kernel level.

Requires admin — macOS asks for your password once to set pmset. No root hacks, no SIP bypass.

Keep Awake

--mode keep-awake

Prevents idle sleep when the lid is open. Good for presentations, long downloads, and monitoring tasks. Uses IOPMAssertion — no sudo required.

No admin needed — runs entirely as a normal user process.

Low Power Mode add-on: Add --low-power to any Lid Closed session to simultaneously enable macOS Low Power Mode. It's automatically restored when the session ends.

Under the Hood

How Lid Closed Mode Works

Most apps that prevent sleep only work while the lid is open. Coffeetosh is different — it keeps your Mac fully operational with the lid physically shut, SSH sessions alive, and an automatic password lock when the lid is opened again. Here is exactly what happens at every step.

system architecture — process flow

  coffeetosh start                 coffeetosh-daemon (detached)
  |                                    |
  |-- sudo pmset -a disablesleep 1     |
  |   (admin password, once)           |
  |-- spawn daemon ──────────────────> |  caffeinate -is  (holds sleep prevention)
  |-- write status.json                |  IOKit lid poll  (every 5 seconds)
  `-- exit                             |
                                       |
  ----------- lid closes ------------- |
                                       |-- save brightness to status.json
                                       |-- set display to minimum
                                       `-- Mac keeps running (SSH, processes...)

  ----------- lid opens -------------- |
                                       |-- CGSession -suspend
                                       `-- macOS password lock screen (OS-level)

  -- stop / timer / SIGTERM ---------- |
                                       |-- restore pmset  (admin password, once)
                                       |-- kill caffeinate
                                       |-- restore brightness
                                       `-- exit

You run coffeetosh start

The CLI reads your arguments — duration, mode, flags. No arguments defaults to Lid Closed mode for 8 hours, or your saved Quick Preset if one is configured.

Admin password — pmset -a disablesleep 1

The CLI prompts for your macOS admin password once via sudo. This runs pmset -a disablesleep 1, which tells the macOS power management kernel extension to ignore all sleep assertions — including the clamshell (lid) sensor. No kernel extensions, no SIP bypass, no credentials stored. The original pmset settings are captured first so they can be restored exactly on stop.

what Coffeetosh sets and restores

# Set at start (requires admin password once):
pmset -a disablesleep 1

# Restored at stop (requires admin password once):
pmset -a disablesleep 0

The daemon spawns detached and the CLI exits

The CLI launches a separate binary — coffeetosh-daemon — as a fully detached background process. The daemon is orphaned from the CLI immediately and survives terminal closes, SSH disconnects, and parent app quits. The CLI writes ~/.coffeetosh/status.json with the session metadata (mode, duration, start time, PID), then exits. From this point the daemon owns everything.

The daemon holds sleep prevention via caffeinate -is

The daemon starts caffeinate -is as a child subprocess. -i prevents idle sleep, -s prevents system sleep. Combined with the pmset flag set in Step 2, macOS cannot sleep regardless of lid state. The caffeinate PID is also written to status.json so it can be targeted for cleanup if the daemon exits unexpectedly.

IOKit polls the lid state every 5 seconds

The daemon reads the AppleClamshellState property from IOPMrootDomain via IOKit on a 5-second tick loop. This is the same low-level registry value that macOS itself reads to detect lid transitions — no third-party drivers, no private APIs. The daemon also watches status.json for an external stop signal (from coffeetosh stop or the menu bar app).

Lid closes → brightness saved, display dimmed

On lid-close detection, the daemon reads the current built-in display brightness via IOKit and saves it to status.json as a restore target. It then sets the built-in display to minimum brightness. The Mac continues running normally — SSH sessions stay alive, processes keep running, the internal display is simply dark. The clamshell state does not interrupt any work.

Lid opens → macOS password lock screen

When the daemon detects lid-open during a Lid Closed session, it immediately calls CGSession -suspend. This is the OS-level screen lock — identical to pressing Ctrl+Cmd+Q. macOS requires your login password before the desktop is accessible. This lock is owned by securityd and the WindowServer Aqua session layer — killing Coffeetosh does not affect it. The daemon also restores the display brightness to the value saved at lid-close.

Session ends → full restore

When the timer expires, when coffeetosh stop is run, or when the daemon receives SIGINT / SIGTERM / SIGHUP, it runs the same teardown: restores pmset to the exact snapshot captured at start (requires admin password once), terminates the caffeinate subprocess, restores the saved display brightness, and marks the session inactive in status.json. Your Mac returns to its normal sleep behaviour.

About the password prompts: Coffeetosh asks for admin permission exactly twice — once at start (to set pmset -a disablesleep 1) and once at stop (to restore it). The password is never stored. It is piped to sudo -S via stdin with terminal echo disabled and the pipe is closed immediately. If your sudo auth token is still valid, no prompt appears at all.

Lid-open lock security: CGSession -suspend calls into the macOS Security Server and WindowServer. It is the same code path as the system Ctrl+Cmd+Q keyboard shortcut and cannot be circumvented by stopping or killing Coffeetosh. If Coffeetosh is force-quit before the lid fires, the lid opens normally — no security degradation, simply no auto-lock.

CLI Reference

All Commands

Every command available via the coffeetosh CLI. Arguments in [brackets] are optional.

start

Start a session

Prevent your Mac from sleeping. Without arguments, Coffeetosh uses your saved Quick Preset. With arguments, you can specify duration and mode directly.

zsh — examples

$ coffeetosh start                           # Use saved Quick Preset
$ coffeetosh start 8                          # Lid Closed, 8 hours
$ coffeetosh start 2 --mode keep-awake        # Keep Awake, 2 hours
$ coffeetosh start 8 --low-power              # Lid Closed + Low Power Mode
$ coffeetosh start 0                          # Start indefinitely
$ coffeetosh start --minutes 90               # Lid Closed, 90 minutes
$ coffeetosh start -m 45                      # Shorthand for --minutes

Flag	Default	Description
[hours]	8	Session duration in hours. Use `0` for indefinite.
--mode <mode>	coffeetosh	`coffeetosh` / `lid-closed` or `keep-awake` / `a` or `b`
--low-power	off	Enable macOS Low Power Mode for the session (Lid Closed only). Auto-restores on stop.
--minutes / -m	—	Specify duration in minutes instead of hours. E.g. `-m 90`

stop

Stop the current session

Ends the active session, kills the daemon, and restores all system sleep settings to their original state — including pmset and Low Power Mode if they were modified.

zsh

$ coffeetosh stop

If Lid Closed mode was active, stop will prompt for your admin password once to restore pmset settings.

status

View current session state

Displays whether Coffeetosh is active, the current mode, start time, remaining duration, daemon PID, lid state, and any active options.

zsh — output example

$ coffeetosh status
Coffeetosh: ACTIVE (Mode: Lid Closed)
Started: 2025-01-15 22:10:04
Duration: 8h | Remaining: 6h 42m
Daemon PID: 4821 (running)
Lid: Closed 🔒

add

Extend a running session

Add more time to an already-active session without restarting it. Defaults to 30 extra minutes if no amount is specified.

zsh — examples

$ coffeetosh add          # Add 30 minutes (default)
$ coffeetosh add 60        # Add 60 minutes
$ coffeetosh add 1.5       # Add 1.5 hours (90 minutes)

preset

Save a Quick Preset

Store your preferred mode and duration so that running coffeetosh start with no arguments immediately applies it. Syncs with the app's Settings panel.

zsh — examples

$ coffeetosh preset                              # Show current preset
$ coffeetosh preset set keep-awake 2h            # Save: Keep Awake, 2h
$ coffeetosh preset set lid-closed 8h            # Save: Lid Closed, 8h
$ coffeetosh preset set lid-closed 0             # Save: Lid Closed, indefinite
$ coffeetosh preset set keep-awake 30m           # Save: Keep Awake, 30 min
$ coffeetosh preset clear                         # Remove saved preset

Duration format	Example
Hours	`2h`, `8h`, `24h`
Minutes	`30m`, `90m`
Indefinite	`0` or `inf`

battery

Check battery status

Shows current battery percentage, charging state, power source, and estimated time remaining — parsed cleanly from pmset.

zsh — output example

$ coffeetosh battery
Battery: 79% — discharging
Source:  Battery Power
Time:    3:42 remaining

mac-temp

Read CPU & GPU temperature

Runs powermetrics to sample SMC sensors and display CPU die and GPU die temperatures. Requires admin password once per invocation. Alias: temp.

zsh — output example

$ coffeetosh mac-temp
Mac temperature (admin password may be required):
CPU die temperature: 48.32 C
GPU die temperature: 41.85 C

Uses standard macOS powermetrics — no third-party sensors or kernel extensions needed.

install-cli

Install the CLI tool system-wide

Creates a symlink at /usr/local/bin/coffeetosh pointing to the binary bundled inside the .app. After this, you can run coffeetosh from any terminal session.

zsh

$ coffeetosh install-cli
coffeetosh installed at /usr/local/bin/coffeetosh
   Run: coffeetosh status

help

Print the usage guide

Displays the built-in usage reference with all commands, modes, options, and examples inline in your terminal.

zsh

$ coffeetosh help
$ coffeetosh --help
$ coffeetosh -h

Workflow Tip

Using Quick Preset

Quick Preset lets you save your most-used session so that a single coffeetosh start command kicks it off instantly — no flags required. Set it once, and it's available in both the CLI and the menu bar app.

zsh — typical workflow

# 1. Save your preset once
$ coffeetosh preset set lid-closed 8h
Quick Preset saved: Lid Closed - 480m
   coffeetosh start  ← will now use this preset

# 2. From now on, just run:
$ coffeetosh start
Quick Preset: Lid Closed - 480m
☕ Coffeetosh started!
   Mode: Lid Closed
   Duration: 8h
   Daemon PID: 5204

Advanced

Remote & SSH Use

Because Coffeetosh runs as a daemon, you can start sessions remotely from another machine over SSH. The daemon stays alive even after you close the SSH connection.

zsh — remote start via SSH

# Start a 12-hour Lid Closed session on a remote Mac
$ ssh user@macbook.local "coffeetosh start 12"

# Check session status remotely
$ ssh user@macbook.local "coffeetosh status"

# Stop remotely
$ ssh user@macbook.local "coffeetosh stop"

Note: The Lid Closed mode admin password prompt only works when you are logged in locally (or via a TTY). For fully remote/headless use, set a Quick Preset with keep-awake mode, which requires no sudo.

Help

Troubleshooting

command not found: coffeetosh

The CLI symlink hasn't been created yet. Open the Coffeetosh app from your Applications folder, click the menu bar icon → Settings → Install CLI Tool. Or run coffeetosh install-cli once you can locate the binary inside the app bundle.

Admin password prompt on every start

Lid Closed mode (--mode coffeetosh) requires pmset -a disablesleep 1, which is an admin-level pmset change. macOS prompts for your password because this modifies a system-level power setting. Keep Awake mode (--mode keep-awake) never prompts for a password.

Session shows INACTIVE right after start

The daemon needs a brief moment to write its PID to the status file. Wait one second and run coffeetosh status again. If it still shows inactive, check that the Coffeetosh app is installed in /Applications (the daemon binary is embedded inside it).

Mac woke up even with Coffeetosh active

Some hardware events — like opening the lid, an incoming phone call, or a Power Nap wake — can override sleep assertions. Coffeetosh prevents software-initiated sleep, but hardware and user interactions always take priority. If you opened the lid, that's expected behavior.

coffeetosh stop says "not active" after a crash

If the daemon crashed unexpectedly, run coffeetosh stop to force-restore pmset settings. If the session file is stale, you can also manually reset with: sudo pmset -a disablesleep 0 to ensure sleep is re-enabled.

How do I uninstall Coffeetosh?

Stop any active session first with coffeetosh stop. Then remove the app from /Applications. To remove the CLI symlink: sudo rm /usr/local/bin/coffeetosh. All preferences are stored in ~/Library/Application Support/Coffeetosh/ which you can also delete.