One small binary that makes a Linux laptop behave.
Cap the battery charge, read every sensor, keep the machine awake, switch the screens off.
$ laptopctl
Battery: BAT0
Power: plugged in
Status: Not charging
Charge: 96%
Start threshold: 75%
End threshold: 80%
Health: 90.9% (80 cycles)
Sensors: 47.8°C max, fans 2970 RPM
awake: on (pid 492677, 11h24m left)
display: stays onThat is a laptop on its charger that is not charging: the battery is above its 80% stop threshold, so the machine runs from the wall and leaves the cells alone. It is also being held awake for another eleven hours, and it will let go on its own.
- Battery care. Set the charge thresholds that keep a docked battery away from 100%, with presets for daily use and for a full charge before a trip. See capacity, health and cycle count.
- Keep awake. Like Amphetamine or
caffeinateon macOS: stay awake for a duration, until a time of day, or for the working day, then go back to normal by itself. - Screens off. Turn every display off right now while the laptop keeps working. The next key press or mouse movement brings them back.
- Sensors. Every temperature and fan the kernel knows about, without installing
lm-sensors. - Self-updating.
laptopctl updateinstalls the latest release, verified against its checksum.
It is a single static binary with no configuration file and no runtime dependencies. Nothing runs in the background unless you ask for it.
curl -fsSL https://raw.githubusercontent.com/8ff/laptopctl/main/install.sh | shThat downloads the latest release for your machine (x86-64 or arm64), checks it against the
release's SHA256SUMS and installs it to ~/.local/bin/laptopctl. It doesn't use sudo.
From then on, laptopctl update keeps it current.
Set LAPTOPCTL_INSTALL_DIR to install somewhere else. install.sh is short if
you would like to read it first.
Other ways to install
By hand, the same steps the script runs:
arch=$(uname -m | sed 's/x86_64/amd64/; s/aarch64/arm64/')
cd "$(mktemp -d)"
curl -fsSLO "https://github.com/8ff/laptopctl/releases/latest/download/laptopctl-linux-$arch"
curl -fsSLO "https://github.com/8ff/laptopctl/releases/latest/download/SHA256SUMS"
sha256sum --check --ignore-missing SHA256SUMS
install -Dm755 "laptopctl-linux-$arch" ~/.local/bin/laptopctlWith Go:
go install github.com/8ff/laptopctl@latestFrom source:
git clone https://github.com/8ff/laptopctl
cd laptopctl
go build -o ~/.local/bin/laptopctl .Run laptopctl on its own for the overview above, or laptopctl help for every command.
laptopctl battery # charge, thresholds, health
laptopctl battery health # design and full capacity, health, cycles
laptopctl battery daily # stop charging at 80%, resume below 75%
laptopctl battery full # allow a full charge (0/100), for travel days
laptopctl battery set 60 70 # any start and stop thresholds you like
laptopctl battery persist # reapply the current thresholds at every boot$ laptopctl battery health
Battery: BAT0
Design capacity: 50.5 Wh
Full capacity: 45.9 Wh
Health: 90.9%
Cycles: 80Writing thresholds needs root, so set, daily, full and persist ask for sudo
themselves. Everything else runs as you.
persist installs a small systemd unit, laptopctl-battery.service, for hardware that
forgets its thresholds when powered off. laptopctl battery persist 75 80 stores specific
values instead of the current ones. Many laptops, ThinkPads among them, remember the
thresholds in firmware and don't need it. To remove it:
sudo systemctl disable --now laptopctl-battery.service
sudo rm /etc/systemd/system/laptopctl-battery.service
sudo systemctl daemon-reloadlaptopctl awake on # stay awake until "awake off"
laptopctl awake on --for 90m # ...for a duration (30m, 13h, 1h30m)
laptopctl awake on --until 17:30 # ...until a local time, 24-hour clock
laptopctl awake workday # ...until 21:00 today (--end 22:30 to change)
laptopctl awake toggle # on if off, off if on
laptopctl awake off
laptopctl awake # is it on, and for how much longer?By default both the system and the display stay awake. Add --allow-display-sleep to let the
screen blank and lock while the machine keeps running.
workday differs from --until in one way: started after the end time, it refuses instead
of rolling over to tomorrow and holding the laptop awake for almost a day.
awake toggle makes a good keyboard shortcut: add it under Settings → Keyboard → View and
Customize Shortcuts → Custom Shortcuts.
laptopctl screen off # screens off until the next key press or mouse movement
laptopctl screen on # bring them back, for example over SSH
laptopctl screen # are they on?screen off waits for the keyboard and mouse to be still for a second, so the key that ran
the command doesn't wake the screens straight away. It then stays running until you wake
them; Ctrl+C turns them back on too.
To leave a long job running overnight with the screens dark:
laptopctl awake on --until 08:00
laptopctl screen offStart awake first, because GNOME switches the screens back on when keep-awake begins.
$ laptopctl sensors
coretemp
Package id 0: 46.0°C
Core 0: 45.0°C
Core 1: 45.0°C
Core 2: 46.0°C
Core 3: 46.0°C
nvme
Composite: 42.9°C
Sensor 1: 42.9°C
thinkpad
CPU: 44.0°C
fan1: 2969 RPM(Shortened. The real output lists every hwmon device.)
laptopctl version
laptopctl update --check # is there a newer release?
laptopctl update # install itupdate downloads the binary for your architecture from the latest
GitHub release, checks it against the release's
SHA256SUMS, runs it once to make sure it works on your machine, and only then swaps it in
atomically. A failed update leaves the installed version untouched. laptopctl never checks for
updates on its own; it only talks to the network when you run update.
The checksum is published next to the binary, so it guards against a corrupted download, not against a compromised release. Some commands run as root, so if you would rather not trust release binaries, build from source.
| Feature | Needs |
|---|---|
| Battery status and health | A battery under /sys/class/power_supply/BAT* |
| Charge thresholds | A kernel driver that exposes charge_control_start_threshold and charge_control_end_threshold |
| Sensors | hwmon sensors under /sys/class/hwmon |
| Keep awake | A GNOME session |
| Screens | GNOME on Mutter |
When a battery doesn't expose the thresholds, laptopctl says so instead of failing silently; the charge limit may then be a BIOS setting. Developed and tested on a ThinkPad running Debian 13 with GNOME 48. Reports from other hardware are welcome.
No magic, and nothing that outlives its purpose:
- Battery: reads and writes the kernel's
power_supplyfiles in sysfs. - Sensors: reads hwmon directly.
- Keep awake: a small detached helper holds a GNOME SessionManager inhibitor over D-Bus
and exits when the time is up or you run
awake off. Its state lives in$XDG_RUNTIME_DIR/laptopctl. - Screens: sets Mutter's
PowerSaveModeand watches Mutter's idle monitor for the first input.
go test ./...
go vet ./...The tests run against a fake sysfs tree and a local HTTP server, so they need neither a battery nor a network.
Pushing a tag such as v1.2.3 runs the release workflow,
which builds the static binaries, writes SHA256SUMS and publishes the GitHub release that
laptopctl update installs from.
A fork can ship its own updates by building with
-ldflags "-X main.releaseURL=https://api.github.com/repos/OWNER/REPO/releases/latest".
Copyright © 2026 8ff
laptopctl is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. It comes with no warranty. See LICENSE.