qmk-rgb

Wobkey RGB CLI

Cross-platform CLI for Linux, macOS, and Windows. 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
# Raw mode IDs are zone-specific; ID 17 is Backlight-only
./wobkey rgb mode 17 --zone backlight
./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.

Platform Setup

The tool uses hidapi for cross-platform HID access. Most platforms need no configuration, but Linux requires extra setup.

Linux

The tool accesses keyboards via hidraw which requires special 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.

macOS

No setup required. macOS applications access HID devices directly through IOKit.

Windows

No setup required. Windows applications access HID devices directly through the Windows HID API.

After Linux setup, 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
wobkey rgb --device <path> ...	Specify HID device path

Architecture

cmd/wobkey/       # Cobra-based CLI
cmd/wobkey/rgb/   # RGB subcommands
internal/device/  # HID discovery + keyboards.json loader
internal/hid/     # Cross-platform HID access (hidapi)
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 feature reports.

• 0x07 — Custom set value
• 0x08 — Custom get value
• Lighting channels: 0x02 logo, 0x03 backlight, 0x04 side lighting
• RGB values: brightness 0x01, effect 0x02, speed 0x03, color 0x04