keylightd
keylightd is a lightweight daemon that automatically discovers and controls Elgato Key Light devices on your network via mDNS. It exposes a CLI, HTTP API, and Unix socket so you can manage your lights from scripts, desktop apps, or anything that speaks HTTP or JSON.
Quick Start
1. Install
- Homebrew
- Arch (AUR)
- Binary Release
brew tap jmylchreest/keylightd && brew install keylightd
paru -S keylightd-bin
Download the latest release from GitHub Releases.
2. Start the daemon
keylightd
The daemon will begin discovering Key Lights on your local network automatically.
3. Create an API key
This is required for HTTP API access. The CLI and Unix socket don't need keys.
keylightctl api-key add my-key
4. Control a light
# List discovered lights
keylightctl light list
# Set brightness to 80%
keylightctl light set <LIGHT_ID> brightness 80
See the Getting Started guide for the full setup walkthrough.
Ways to Control Your Lights
keylightd gives you several interfaces — pick whichever fits your workflow.
| Interface | Description | Docs |
|---|---|---|
CLI (keylightctl) | Command-line tool for scripting and quick adjustments | Lights CLI · Groups CLI |
| HTTP REST API | Remote control on port 9123 with Bearer token auth and an OpenAPI spec | Lights HTTP · Groups HTTP · API Reference |
| Unix Socket | Low-latency local control via $XDG_RUNTIME_DIR/keylightd.sock | Lights Socket · Groups Socket · Socket Reference |
| System Tray App | Desktop GUI built with Wails for point-and-click control | Tray App |
| GNOME Extension | Native GNOME Shell integration | GNOME Extension |
| Waybar Module | Status bar widget for Wayland compositors | Waybar |
Key Concepts
- Auto-discovery — The daemon finds Key Lights on your network via mDNS. No manual IP configuration needed.
- Groups — Organize lights into named groups to control multiple lights with a single command. See Groups CLI.
- API Keys — HTTP access is secured with Bearer token authentication. Generate keys with
keylightctl api-key add. - WebSocket Events — Subscribe to real-time state changes over the HTTP API for reactive integrations.
Learn More
- Getting Started — Installation, first run, and initial configuration
- Lights CLI — Full CLI reference for individual light control
- Groups CLI — Create and manage light groups
- HTTP REST API Reference — OpenAPI spec and endpoint documentation
- Unix Socket API Reference — Protocol reference for local socket communication
- Desktop Apps — Tray app, GNOME extension, and Waybar integration
Found an issue or want to contribute? Visit the GitHub repository.