litra

On macOS, Linux, or Windows, you can install the litra crate using Rust's package manager, Cargo. Ensure Rust is installed on your machine first.

cargo install litra

On macOS or Linux, you can install the latest version of litra using Homebrew.

Note for older installations: If you installed via the timrogers/homebrew-tap before January 30, 2026, you should reinstall it from homebrew-core by running: brew uninstall litra && brew install litra.

On Linux, you must configure udev permissions to allow non-root users to manage Litra devices.

1. Add your user to the video group: sudo usermod -aG video $USER
2. Copy the 99-litra.rules file into /etc/udev/rules.d/.
3. Reload rules and trigger the changes as root: sudo udevadm control --reload-rules sudo udevadm trigger

sudo usermod -aG video $USER
# After copying 99-litra.rules to /etc/udev/rules.d/
sudo udevadm control --reload-rules
sudo udevadm trigger

On macOS, Linux, or Windows, you can download the latest release directly from GitHub.

1. Download the latest release for your platform from the GitHub releases page.
2. Add the binary to your $PATH.
3. For the best experience, name the binary litra on macOS/Linux or litra.exe on Windows.

The library supports the following Logitech Litra models:

• LitraGlow: Streaming light with TrueSoft.
• LitraBeam: LED streaming key light.
• LitraBeamLX: Dual-sided RGB streaming key light (supports back-side color/brightness controls).

// Check if a device has a colorful back side
if device.device_type().has_back_side() {
    // ...
}

The LitraMcpServer implements the Model Context Protocol (MCP) to allow AI agents and other clients to control Litra hardware via standard input/output (stdio).

Architecture

• Transport: Uses stdio for communication.
• Routing: Uses a tool_router to map incoming MCP tool calls to specific Rust handler functions.
• Error Handling: Errors are returned as McpError and communicated back to the client as text content within a CallToolResult error block.
• Lifecycle: The server is initialized via LitraMcpServer::new(), served via .serve(stdio()), and enters a waiting state with .waiting().

Implementation Note

To run the MCP server, the handle_mcp_command() function must be called. This initializes tracing (logging to stderr) and starts the Tokio runtime to manage the asynchronous MCP service.

Most litra CLI commands allow you to target specific devices instead of all connected devices. You can use one of the following three methods to filter your target. Note that these options are mutually exclusive: you cannot use more than one at a time.

• --serial-number (-s): Target a device by its unique serial number.
• --device-path (-p): Target a device by its system path (useful if the device lacks a serial number).
• --device-type (-t): Target all devices of a specific type. Supported types are glow, beam, or beam_lx.

# Examples of targeting specific devices
litra on --serial-number "12345"
litra brightness --device-path "/dev/bus/usb/001/002"
litra off --device-type beam

To interact with Logitech Litra lights, you must first create a Litra context. This context manages the underlying HID API and provides methods to discover connected devices. Use Litra::new() to initialize the context and get_connected_devices() to retrieve an iterator of available Device objects. If you need to detect newly plugged-in devices, call refresh_connected_devices() on the context.

use litra::Litra;

let context = Litra::new().expect("Failed to initialize litra.");
for device in context.get_connected_devices() {
    // Work with device...
}

To prevent the CLI from checking for new versions on GitHub, set the following environment variable:

LITRA_DISABLE_UPDATE_CHECK