kblight

A tiny CLI that sets the keyboard backlight on Apple Silicon Macs. Single Swift file, no dependencies, no Xcode project, no sudo, no entitlements.

kblight 0.5      # 50% brightness
kblight 0.0      # off
kblight 1.0      # full
kblight get      # -> 0.5000

Why this exists

Setting the keyboard backlight from a script on Apple Silicon is harder than it should be. The obvious approaches don't work:

• Writing the IOKit KeyboardBacklightBrightness property succeeds but doesn't change the LED — it's a state mirror, not a control register. corebrightnessd owns the actual PWM hardware (AppleARMPWMDevice) and ignores that property.
• **AppleSMC / AppleLMUController** was the Intel path; it doesn't exist on Apple Silicon.
• Sending HID brightness keys is increment/decrement only, requires Accessibility permission, and is fragile.

kblight instead calls into CoreBrightness.framework (private) the same way the system UI does, via the KeyboardBrightnessClient ObjC class. That's the path corebrightnessd actually responds to, so writes propagate to the LED immediately.

Install

swiftc kblight.swift -o kblight
sudo install -m 755 kblight /usr/local/bin/kblight

Requirements: macOS 12+, Apple Silicon, Xcode command-line tools (for swiftc).

Usage

kblight <0.0-1.0>   Set brightness (clamped to range)
kblight get         Print current brightness as a float
kblight ids         List keyboard backlight IDs (debugging)
kblight --help      Show help

Exit code is 0 on success, non-zero on failure with a message on stderr.

If multiple backlit keyboards are attached, kblight targets the built-in one if present, otherwise the first one reported by CoreBrightness. Pass kblight ids to see all of them.

From Shortcuts / Focus modes

Add a "Run Shell Script" action with:

/usr/local/bin/kblight 0

Trigger it from a Focus mode automation. No password prompts, no Accessibility grants are needed, it just works as the user.

Troubleshooting

**No keyboard backlight IDs reported by CoreBrightness** — this Mac may not have a built-in backlit keyboard, or no backlit keyboard is currently attached. Magic Keyboards (the external ones) generally don't expose a backlight.

**Could not find ObjC class 'KeyboardBrightnessClient'** — Apple has likely renamed or removed the private API in this macOS version. Re-discover it with:

dyld_info -exports /System/Library/PrivateFrameworks/CoreBrightness.framework/CoreBrightness | grep -i keyboard

The sibling class BrightnessSystemClient (in the same framework) exposes a more generic setProperty:withKey:keyboardID: shape that's likely to survive refactors of the convenience class.

LED doesn't move even though get shows the new value — auto-brightness may be overriding your setpoint. CoreBrightness has enableAutoBrightness:forKeyboard: for that, but kblight doesn't expose it; toggle it from System Settings → Keyboard if needed.

How it was built

The path to the working API was not obvious. Notes on the approach (and dead ends) live in CLAUDE.md, including the runtime type-encoding inspection used to derive the C function signatures for the private methods.

Caveat

CoreBrightness.framework is private. Apple does not promise stability for its symbols. If a macOS update breaks kblight, the error message points at the diagnostic command above.

License

MIT.