Docs
--help.This page is generated from the installed binary, so it matches what lidhold --help prints. Start with lidhold doctor: it tells you exactly what will and will not hold on your machine and why.
A hold is either manual (lidhold on, optionally --for 2h) or lease-driven (started by the daemon because an agent holds a lease). lidhold off ends either kind and drops every lease. lidhold status exits 0 when idle and 10 when holding, so it is usable in shell prompts.
Two engines exist. pmset flips pmset disablesleep through a root helper and survives a closed lid on AC or battery. assert takes IOKit power assertions with no root and only survives a closed lid in clamshell mode (external display plus AC). lidhold on picks pmset when the helper is installed and refuses to start an assert hold that would not survive the lid unless you pass --force.
Connecting an agent. Claude Code, Cursor, and GitHub Copilot CLI are supported, and lidhold setup detects and wires every one of them it finds. To add one later, or to check: lidhold hooks install claude-code, lidhold hooks install cursor, or lidhold hooks install copilot, then restart any open session of that agent so it loads the hooks. From then on there is nothing to do per session: the agent calls lidhold hook <agent> on its own events and the lease follows the work. lidhold hooks status <agent> shows what is installed; lidhold hooks remove <agent> undoes it and leaves the rest of that agent's settings untouched.
A lease is a named entry with a TTL. The daemon holds while any lease is alive and releases when the last one expires, so a crashed agent can never pin the machine. Claude Code refreshes its lease on session start, every tool call (before and after), shortens it to a 2-minute grace on Stop, and drops it on SessionEnd. Cursor maps the same way from its sessionStart, beforeSubmitPrompt, preToolUse, postToolUse, stop, and sessionEnd hooks, written to ~/.cursor/hooks.json. Copilot CLI maps the same way from sessionStart, userPromptSubmitted, preToolUse, postToolUse, agentStop, and sessionEnd, written under hooks in ~/.copilot/config.json with its comment header preserved. Defaults live in the config file under [hooks]: lease_ttl = "30m", stop_grace = "2m".
$ lidhold lease take my-agent --ttl 30m $ lidhold lease list $ lidhold lease release my-agent
lidhold run -- <command> holds for exactly the command's lifetime. The lease is taken before the child starts, refreshed every third of lease_ttl while it runs, and dropped when it exits. The exit code passes through (a signal-killed child maps to 128 plus the signal), SIGINT, SIGTERM and SIGHUP are forwarded to the child, and stdout is untouched; lidhold speaks only on stderr.
$ lidhold run -- cargo test
lidhold: holding while `cargo test` runs (lease run:cargo:78357)
...
lidhold: `cargo` finished, lease releasedBattery: releases below the floor when on battery (default 20%, 0 disables). Thermal: releases when macOS thermal pressure reaches the ceiling (default heavy). Thermal outranks battery. Both apply to manual and lease holds, refuse to start a hold when already tripped (exit 2, --force overrides), and are checked every 30 seconds while holding. Configure with lidhold config init then edit the file, or per hold with --min-battery and --max-thermal.
Manual holds and the guards are free. Agent hooks and leases need a license after a 7-day trial that starts on first use. One key covers up to 3 machines; lidhold license deactivate frees a slot. The machine is identified by a hash of its hardware UUID, so an OS reinstall does not use a second slot. The daemon re-checks the key weekly; a failed network call never revokes anything, so a closed laptop keeps working offline.
$ lidhold --help
Keep your Mac awake with the lid closed while agents work.
Usage: lidhold <COMMAND>
Commands:
on Hold the Mac awake now
off Release the hold
status Show current state
doctor Diagnose what will and won't hold on this machine
helper Manage the privileged helper (needed for real closed-lid hold)
daemon Manage the background daemon that keeps holds alive
setup Finish setup for an already-installed binary: helper, daemon, hooks, doctor
install Install lidhold and the privileged helper system-wide (run with sudo)
uninstall Remove the system-wide install and the privileged helper (run with sudo)
config Manage guard thresholds
run Hold for exactly as long as a command runs: lidhold run -- cargo test
lease Agent-driven holds: the Mac stays awake while any lease is alive
hook Entry point for an agent's hook config; reads the event from stdin
hooks Install or remove the hook config that makes an agent take leases
license Activate, check, or release this machine's license
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
-V, --version Print version
$ lidhold on --help
Hold the Mac awake now
Usage: lidhold on [OPTIONS]
Options:
--for <FOR> Release automatically after this long, e.g. 2h, 45m
--engine <ENGINE> Force an engine instead of auto-selecting [possible values: pmset, assert]
--force Don't warn when the chosen engine won't survive lid close, and ignore guards
--min-battery <MIN_BATTERY> Release below this battery percentage; 0 disables the battery guard
--max-thermal <MAX_THERMAL> Release at this thermal pressure or above [possible values: nominal, moderate, heavy, trapping, sleeping]
-h, --help Print help
$ lidhold off --help
Release the hold
Usage: lidhold off
Options:
-h, --help Print help
$ lidhold status --help
Show current state
Usage: lidhold status [OPTIONS]
Options:
--json
-h, --help Print help
$ lidhold doctor --help
Diagnose what will and won't hold on this machine
Usage: lidhold doctor
Options:
-h, --help Print help
$ lidhold run --help
Hold for exactly as long as a command runs: lidhold run -- cargo test
Usage: lidhold run <COMMAND>...
Arguments:
<COMMAND>...
Options:
-h, --help Print help
$ lidhold lease take --help
error: unrecognized subcommand 'lease take'
tip: a similar subcommand exists: 'lease'
Usage: lidhold <COMMAND>
For more information, try '--help'.
$ lidhold hooks install --help
error: unrecognized subcommand 'hooks install'
tip: some similar subcommands exist: 'uninstall', 'hook', 'hooks'
Usage: lidhold <COMMAND>
For more information, try '--help'.
$ lidhold license activate --help
error: unrecognized subcommand 'license activate'
tip: some similar subcommands exist: 'lease', 'license'
Usage: lidhold <COMMAND>
For more information, try '--help'.
$ lidhold config --help
Manage guard thresholds
Usage: lidhold config <COMMAND>
Commands:
init Write a commented config file with the default thresholds
show Show the effective thresholds and where they came from
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
$ lidhold setup --help
Finish setup for an already-installed binary: helper, daemon, hooks, doctor
Usage: lidhold setup
Options:
-h, --help Print help