qmk-light is a CLI utility that reads and sets keyboard backlight brightness on VIA-compatible QMK devices over HID.

Code in this repo is still experimental and it might not be complete, use on your own risk!

Install from AUR.

paru -S qmk-light-bin

Download the matching package from the latest GitHub release:

• qmk-light_<version>_amd64.deb
• qmk-light_<version>_arm64.deb

Then install it:

sudo dpkg -i qmk-light_<version>_<arch>.deb

If dpkg reports missing dependencies, run:

sudo apt-get install -f

Install build/runtime dependencies:

sudo apt-get update
sudo apt-get install -y g++ libhidapi-dev

Compile:

g++ -std=c++17 -O2 qmk-light.cpp -lhidapi-hidraw -o qmk-light

Optional install:

sudo install -m 0755 qmk-light /usr/local/bin/qmk-light

List compatible devices:

qmk-light --list

Read brightness (uses the first compatible device by default):

qmk-light --get-brightness

Read brightness for a specific device index or path:

qmk-light --device 0 --get-brightness
qmk-light --device "/dev/hidraw3" --get-brightness

Set brightness:

qmk-light --set-brightness 75
qmk-light --set-brightness +5
qmk-light --set-brightness -10

List standard RGB effect modes:

qmk-light --list-effects

Get current effect ID:

qmk-light --get-effect

Set effect ID (0-255):

qmk-light --set-effect 12

Get current effect speed:

qmk-light --get-effect-speed

Set effect speed (0-255):

qmk-light --set-effect-speed 128

Get current color (Hue, Saturation):

qmk-light --get-color

Set color (Hue 0-255, Saturation 0-255):

qmk-light --set-color 128,255

Use the first compatible device explicitly (same selection as default behavior):

qmk-light --first-device --set-brightness 50

Run quietly (suppress error messages; useful for scripts):

qmk-light --quiet --get-brightness
qmk-light -q --device 0 --set-brightness 50

Show help:

qmk-light --help

If you encounter the error Selected device does not expose a supported brightness channel or if the CLI only works when run with sudo, it is likely a permissions issue with your udev rules. Your user needs read/write access to the /dev/hidraw* device node.

1. Install standard QMK rules: Many distributions provide a qmk package or qmk-udev-rules package that includes rules for most standard QMK/VIA keyboards. Try installing that first and reloading your udev rules.

2. Create a custom udev rule: If your keyboard is a vendor fork or not in the official QMK database, you will need to create a custom rule.

   First, find your keyboard's Vendor ID (vid) and Product ID (pid) by running:

   qmk-light --list

   Note: If the list is empty, try running sudo qmk-light --list.

   Create a new file at /etc/udev/rules.d/50-qmk-light.rules with the following content, replacing XXXX and YYYY with your actual vid and pid:

   KERNEL=="hidraw*", SUBSYSTEM=="hidraw", ATTRS{idVendor}=="XXXX", ATTRS{idProduct}=="YYYY", MODE="0660", TAG+="uaccess"
   

3. Apply the rules: Reload the udev rules and force them to apply:

   sudo udevadm control --reload-rules
   sudo udevadm trigger --subsystem-match=hidraw --action=add

   (Alternatively, you can just unplug and replug your keyboard).

Rebuild and run a quick check:

g++ -std=c++17 -O2 qmk-light.cpp -lhidapi-hidraw -o qmk-light
./qmk-light --list

This repository includes a GitHub Actions workflow that:

• Builds Linux binaries for amd64 and arm64
• Packages .deb files for both architectures
• Uploads all artifacts to a GitHub release

To publish a release:

1. Create and push a tag like v1.2.3
2. Wait for the Build and Release workflow to complete
3. Download binaries and .deb packages from the release assets

Example:

git tag v1.2.3
git push origin v1.2.3

• AI was used to write up the code.