macos-keyboard-backlight
No build step, one dependency, no network call, MIT
Your keyboard backlight, finally scriptable.
macOS gives you a slider in System Settings and two keys on the keyboard, and that is the whole interface. There is no way to reach the keyboard backlight from a shell script, a scheduled job, or a Node program. This adds the missing one.
Install
npm i -g macos-keyboard-backlightthen run kbdlight off
See it run
A lit MacBook keyboard seen from above. The command kbdlight auto off && kbdlight off runs, and the backlight drains away key by key.
The command is real and does exactly this. The MacBook is an illustration: the backlight is hardware, so no screen recording can show it.
Why this exists
Almost every part of a Mac can be driven from a script. The keyboard backlight cannot: there is no command, no flag and no supported API. If you want it off between midnight and seven, or dimmed while a recording runs, there is nothing to call.
This package resolves the private CoreBrightness interface at runtime and exposes it as a command and a library, so the backlight becomes one more thing your scripts can control.
No node-gyp. No Xcode. Nothing compiled at install time.
What you get
-
A real command
kbdlight get, set, off, max, auto, list, pulse and sun. Values are clamped to the 0.0 to 1.0 range before they reach the system call, and the help is colour coded on a terminal and plain the moment you pipe it.
-
Blink it as a notification
kbdlight pulse flashes the keyboard and then restores the exact brightness and sensor state it found, so it is safe to hang off an editor hook or a scheduled job. A lock stops two runs from restoring each other's half-finished state.
-
No native build step
No node-gyp, no Xcode, no compiler on the installing machine. The system calls are resolved at runtime through koffi, which ships prebuilt for both architectures.
-
A Node API too
get, set, isAuto and setAuto each take an optional keyboard ID, so you can target one keyboard instead of all of them. keyboardIDs() returns the IDs to pass them.
-
Honest failure
It calls a private Apple framework, so it throws a descriptive Error rather than crashing when that interface is not there. Catch it, do not feature-detect it.
-
One dependency
koffi, and nothing else. Tested on macOS against Node 18, 20, 22 and 24 on every push.
It follows the sun
One command puts the backlight on the sky's schedule: dark through the day, up to a level you choose after sunset, and back down at sunrise. The times move with the season on their own, so there is no clock hour to re-tune in March and again in June.
Sunrise and sunset are computed on your own machine with the NOAA solar algorithm, from coordinates your timezone already implies. No location permission, no lookup service, nothing about where you are leaving the Mac.
An example day
- sunrise
- 06:00
- sunset
- 19:00
- backlight now
- off, it is daylight
The ambient light sensor and the sun schedule are different things, and they compose. Sun mode can hand the daylight hours back to the sensor with --day auto and still hold a fixed level all evening.
kbdlight sun onkbdlight sun off unloads the schedule and restores the exact brightness and sensor state it found.
Install and use
Requires macOS, Apple Silicon or Intel, and Node 18 or newer.
-
Install
Installs a kbdlight command. Use npx instead if you only want to run it once.
npm i -g macos-keyboard-backlight -
Turn it off
Disable the ambient sensor first, otherwise it adjusts the backlight straight back.
kbdlight auto off && kbdlight off -
Put it on the sun's schedule
Dark through the day, lit after sunset, for as long as you leave it armed. Undo it with kbdlight sun off.
kbdlight sun on -
Use it from Node
The same operations as the command, returning numbers and booleans.
node -e "require('macos-keyboard-backlight').set(0.5)"
Restore the ambient light sensor at any time with kbdlight auto on.
Questions people actually ask
The page's structured data carries these same answers, word for word, so anything quoting this page is quoting something you can read here and check.
Can the MacBook keyboard backlight be set from a script?
Not with anything Apple ships: macOS exposes a slider in System Settings and two keys on the keyboard, and no scriptable interface. kbdlight set 0.5 does it, through the private CoreBrightness framework, with no compiler involved.
Why does the keyboard brightness I set change back on its own?
Ambient auto-brightness is re-adjusting it from the light sensor, and it overrides any fixed value. Run kbdlight auto off first, then the level you set holds. Re-enable the sensor later with kbdlight auto on.
Can the keyboard backlight turn on automatically at sunset?
Yes. kbdlight sun on keeps the backlight dark through the day and lights it after sunset, then takes it back down at sunrise. The times are computed on the machine with the NOAA solar algorithm and move with the season, so there is no clock hour to re-tune.
Does it need Xcode, node-gyp or a compiler to install?
No. There is no native build step. The system calls are resolved at runtime through koffi, which ships prebuilt for both Apple Silicon and Intel, and koffi is the only runtime dependency.
Does it send location data anywhere to work out sunrise and sunset?
No. Coordinates are derived from the IANA timezone already set on the machine, which is a city name, and the times are computed locally. There is no location permission prompt, no IP lookup and no network request at any point.
Does it work with an external keyboard?
Any backlit keyboard the system reports is listed by kbdlight list, and get, set, isAuto and setAuto each take an optional keyboard ID so a single keyboard can be targeted instead of all of them.