README.md 6.5 KB
Wobkey RGB CLI
Cross-platform CLI for programmatic control of VIA-compatible keyboard RGB lighting. Designed for automation, scripting, and agent consumption.
Installation
git clone <repo-url>
cd wobkey-rgb
go build -o wobkey ./cmd/wobkey/
Or install globally:
go install ./cmd/wobkey/
Usage
# Discover connected keyboards
./wobkey keyboard info
# RGB commands target Logo, Backlight, and Side by default
./wobkey rgb effect breathing
./wobkey rgb effect rainbow_moving_chevron
./wobkey rgb effect rainbow_moving_chevron --zone backlight
./wobkey rgb brightness 160
./wobkey rgb speed 2
./wobkey rgb color 00ff00
./wobkey rgb mode 17
./wobkey rgb enable
./wobkey rgb disable
./wobkey rgb info
# Select exactly one zone
./wobkey rgb brightness 160 --zone side
# Specify a target device (when multiple are connected)
./wobkey rgb --device /dev/hidraw0 enable
--zone is persistent on rgb and accepts logo, backlight, or side.
Without --zone, commands target Logo, Backlight, and Side in that order.
With --zone, commands target exactly the selected zone. An unsupported
name for an explicit zone fails before the device is opened; a default
command skips unsupported zones and prints a warning on stderr.
All output is machine-parseable JSON when applicable.
Impact 80 Zones and Effects
| Zone | CLI name | VIA channel | Effect IDs |
|---|---|---|---|
| Logo | logo |
2 | 0–6 |
| Backlight | backlight |
3 | 0–45 |
| Side | side |
4 | 0–6 |
Logo and Side share this complete effect family:
| ID | Name |
|---|---|
| 0 | none |
| 1 | wave |
| 2 | fixed_wave |
| 3 | spectrum |
| 4 | breathing |
| 5 | light |
| 6 | shutdown |
Backlight uses the complete Impact 80 catalog:
| ID | Name | ID | Name |
|---|---|---|---|
| 0 | none |
23 | flower_blooming |
| 1 | solid_color |
24 | raindrops |
| 2 | alphas_mods |
25 | jellybean_raindrops |
| 3 | gradient_up_down |
26 | hue_breathing |
| 4 | gradient_left_right |
27 | hue_pendulum |
| 5 | breathing |
28 | hue_wave |
| 6 | band_sat |
29 | pixel_flow |
| 7 | band_val |
30 | digital_rain |
| 8 | band_pinwheel_sat |
31 | solid_reactive |
| 9 | band_pinwheel_val |
32 | solid_reactive_wide |
| 10 | band_spiral_sat |
33 | solid_reactive_multiwide |
| 11 | band_spiral_val |
34 | solid_reactive_cross |
| 12 | cycle_all |
35 | solid_reactive_multicross |
| 13 | cycle_left_right |
36 | solid_reactive_nexus |
| 14 | cycle_up_down |
37 | solid_reactive_multinexus |
| 15 | cycle_out_in |
38 | splash |
| 16 | cycle_out_in_dual |
39 | multisplash |
| 17 | rainbow_moving_chevron |
40 | solid_splash |
| 18 | cycle_pinwheel |
41 | solid_multisplash |
| 19 | cycle_spiral |
42 | starlight |
| 20 | dual_beacon |
43 | starlight_dual_hue |
| 21 | rainbow_beacon |
44 | starlight_dual_sat |
| 22 | rainbow_pinwheels |
45 | riverflow |
ID 39 is multisplash; ID 41 is the distinct solid_multisplash name.
Effect names are resolved independently for each target zone. Compatibility
aliases are off → none, breathe → breathing, rainbow → spectrum
for Logo/Side and rainbow_moving_chevron for Backlight, rainbow_wave →
wave for Logo/Side, and solid → light for Logo/Side and solid_color
for Backlight. The legacy static alias remains accepted as a compatibility
alias for solid.
rgb info reports a zones array with each zone's channel, enabled state,
effect name and ID, brightness, speed, and color. The top-level enabled,
mode, brightness, and speed fields summarize the first selected zone.
If one zone cannot be queried, its record contains an error, other records
are retained, and the process exits non-zero after printing the JSON.
Linux HID Device Permissions
The tool accesses keyboards via /dev/hidraw* which requires root permissions by default. To run without sudo, choose one of the methods below.
Option 1: Quick (Per Session)
Grant your user group access to all HIDRAW devices:
sudo chown root:adm /dev/hidraw*
sudo chmod 660 /dev/hidraw*
This works for the current session only. Permissions reset after reboot.
Option 2: Permanent (udev Rule)
Create a persistent rule for the Wobkey Impact 80:
echo 'SUBSYSTEM=="hidraw", ATTRS{idVendor}=="36b0", ATTRS{idProduct}=="309f", MODE="0660", GROUP="adm"' \
| sudo tee /etc/udev/rules.d/99-wobkey.rules
sudo udevadm control --reload-rules
sudo udevadm trigger
sudo udevadm reload
This makes the Impact 80 accessible to members of the adm group on every boot.
After either option, run the tool as your regular user (no sudo needed).
Supported Keyboards
| Keyboard | VID | PID | Status |
|---|---|---|---|
| Wobkey Rainy 75 | 0x6666 | 0x0001 | Supported |
| Wobkey Impact 80 | 0x36B0 | 0x309F | Supported |
New keyboards can be added to keyboards.json.
CLI Reference
| Command | Description |
|---|---|
wobkey keyboard info |
Discover connected VIA-compatible keyboards |
wobkey rgb enable |
Enable selected lighting zones |
wobkey rgb disable |
Disable selected lighting zones |
wobkey rgb info |
Show per-zone RGB state (JSON) |
wobkey rgb effect <name> |
Set a zone-aware effect by name |
wobkey rgb brightness <val> |
Set brightness (0–255) on selected zones |
wobkey rgb speed <val> |
Set effect speed (0–255) on selected zones |
wobkey rgb color <hex> |
Set color (e.g. ff0000) on selected zones |
wobkey rgb mode <index> |
Set a raw zone-specific effect ID |
wobkey rgb --zone <zone> ... |
Target logo, backlight, or side |
Architecture
cmd/wobkey/ # Cobra-based CLI
cmd/wobkey/rgb/ # RGB subcommands
internal/device/ # HID discovery + keyboards.json loader
internal/hid/ # Pure-Go HID access (/dev/hidraw*)
internal/rgb/ # Effects, colors, state
internal/via/ # VIA protocol implementation
Protocol
Communicates via the QMK Raw HID interface (Usage Page 0xFF60, Usage 0x61) with 32-byte reports. The Linux hidraw transport uses report number 0 followed by the 32-byte QMK payload.
0x07— Custom set value0x08— Custom get value- Lighting channels:
0x02logo,0x03backlight,0x04side lighting - RGB values: brightness
0x01, effect0x02, speed0x03, color0x04