# Wobkey RGB CLI

Cross-platform CLI for programmatic control of VIA-compatible keyboard RGB lighting. Designed for automation, scripting, and agent consumption.

## Installation

```bash
git clone <repo-url>
cd wobkey-rgb
go build -o wobkey ./cmd/wobkey/
```

Or install globally:

```bash
go install ./cmd/wobkey/
```

## Usage

```bash
# Discover connected keyboards
./wobkey keyboard info

# RGB commands
./wobkey rgb enable
./wobkey rgb disable
./wobkey rgb info
./wobkey rgb effect rainbow
./wobkey rgb effect breathing
./wobkey rgb brightness 128
./wobkey rgb speed 100
./wobkey rgb color ff0000
./wobkey rgb mode 7

# Specify a target device (when multiple are connected)
./wobkey rgb --device /dev/hidraw0 enable
```

All output is machine-parseable JSON when applicable.

## 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:

```bash
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:

```bash
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 RGB lighting                      |
| `wobkey rgb disable`            | Disable RGB lighting                     |
| `wobkey rgb info`               | Show current RGB state (JSON)            |
| `wobkey rgb effect <name>`      | Set effect (static, breathing, rainbow…) |
| `wobkey rgb brightness <val>`   | Set brightness (0–255)                   |
| `wobkey rgb speed <val>`        | Set effect speed (0–255)                 |
| `wobkey rgb color <hex>`        | Set solid color (e.g. `ff0000`)          |
| `wobkey rgb mode <index>`       | Set mode by numeric index                |

## 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 VIA protocol over HID reports (report ID `0x52`). RGB is controlled through the QMK `rgblight` subsystem.

- `0x01` — Enable/Handshake
- `0x02` — Set Value
- `0x03` — Get Value