elgato-cli/README.md

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

# 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

./install-plasmoid.sh

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

CLI Usage

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

{"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:

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

Dependencies

• Python 3.11+
• click - CLI framework
• requests - HTTP (exception types only, actual requests use http.client)
• zeroconf - mDNS discovery
• KDE Plasma 6 (for the plasmoid)