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
Take a closer look.
This one is lit the way sun mode would have yours lit at this moment, worked out from your timezone in your browser. It types the commands into its own terminal and runs through them on its own; press one to take over, and it picks the loop back up once you are done.
An illustration, not a photograph. The backlight is hardware, so no screen recording can show it; the real thing is in the clip below.
See it run
A lit MacBook keyboard seen from above. The command kbdlight auto off && kbdlight off runs, and the white 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.
The ambient light sensor is a separate control and the two work together: sun mode can hand the daylight hours back to the sensor with --day auto and still hold a fixed level all evening.
An example day
- sunrise
- 06:00
- sunset
- 19:00
- backlight now
- off, it is daylight
The sensor and the schedule are not alternatives. They compose.
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.
Made to be forked.
The whole tool is about 1,400 lines of plain JavaScript across src/ and bin/, one runtime dependency, and no build step. Nothing has to be compiled before you can read it and nothing has to be configured before you can run it.
MIT, with no contributor agreement to sign. Clone it and the same three suites that guard the published package run on your machine in under a second.
-
Read it in one sitting
src/index.js is the entire CoreBrightness call: it resolves KeyboardBrightnessClient and its selectors at runtime. The rest is a command line, a solar calculator and a pulse.
-
Fork without asking
No permission to request and no queue to join. Fork it, change what you need, and keep the result. If it is useful back here, a pull request is welcome.
-
Worth building on
A menu bar app, a Raycast command, an Apple Shortcuts action, a hook in your editor. The library exports the same functions the command uses: get, set, isAuto, setAuto and keyboardIDs.
gh repo fork noluyorAbi/macos-keyboard-backlight --cloneThen npm install && npm test. Bugs, ideas and pull requests all go to the same place: the issue tracker is open, and so is the discussion of anything you want to build on top of it.
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.