# elgato-cli

CLI tool and KDE Plasma 6 widget to control an Elgato Key Light.

## Features

- **CLI**: Discover, toggle, and adjust brightness/temperature from the terminal
- **KDE Plasmoid**: System tray widget with power switch, brightness and temperature sliders
- **Shared config**: CLI discovery saves the light IP, plasmoid picks it up automatically
- **Resilient**: Retries and HTTP/1.0 workarounds for the light's flaky TCP stack

## Installation

### CLI

```bash
# With pipx (recommended, system-wide)
pipx install /path/to/elgato-cli

# Or in a venv
python3 -m venv .venv
.venv/bin/pip install -e .
```

### Plasmoid

```bash
./install-plasmoid.sh
```

Then add "Elgato Key Light" to your panel or system tray.

## CLI Usage

```bash
# First run: discover light on the network (mDNS)
elgato discover

# Or configure manually
elgato --host 192.168.230.111 status

# Power
elgato on
elgato off
elgato toggle

# Brightness (3-100)
elgato brightness          # get
elgato brightness 50       # set

# Color temperature (143-344 mired, or Kelvin with -k)
elgato temperature         # get
elgato temperature 250     # set in mired
elgato temperature 4000 -k # set in Kelvin

# Device info
elgato info
```

Global `--host` and `--port` flags override the saved config.

## Plasmoid

The widget communicates directly with the light's HTTP API (no CLI dependency). It reads the shared config from `~/.config/elgato-cli/config.json`, or you can set the host/port in the widget settings.

Features:
- System tray icon (changes based on light state)
- Middle-click to toggle power
- Brightness and temperature sliders (value sent on release)
- 3-second polling to keep state in sync

## Elgato HTTP API

The light exposes a REST API on port 9123 with no authentication:

| Endpoint | Method | Description |
|---|---|---|
| `/elgato/lights` | GET | Current state |
| `/elgato/lights` | PUT | Set state |
| `/elgato/accessory-info` | GET | Product info |
| `/elgato/lights/settings` | GET | Light settings |

PUT payload:
```json
{"numberOfLights": 1, "lights": [{"on": 1, "brightness": 50, "temperature": 200}]}
```

Temperature is in mired: `mired = 1000000 / kelvin` (143 = 7000K cool, 344 = 2900K warm).

## Known Quirks

The Elgato Key Light firmware has a buggy TCP stack:
- HTTP/1.1 GET requests get connection-reset — we use HTTP/1.0 for reads
- HTTP/1.0 PUT requests get 400 Bad Request — we use HTTP/1.1 with `Connection: close` for writes
- Rapid connections can lock up the light (requires power cycle) — requests are retried with 1s delay

## Config

Stored at `~/.config/elgato-cli/config.json`:

```json
{"host": "192.168.230.111", "port": 9123, "name": "Elgato Key Light"}
```

## Dependencies

- Python 3.11+
- [click](https://click.palletsprojects.com/) - CLI framework
- [requests](https://requests.readthedocs.io/) - HTTP (exception types only, actual requests use `http.client`)
- [zeroconf](https://github.com/python-zeroconf/python-zeroconf) - mDNS discovery
- KDE Plasma 6 (for the plasmoid)