# How to Configure OpenLogi for Logitech Devices: Complete TOML Guide

> Master OpenLogi configuration for Logitech devices. Learn to customize DPI, bindings, and lighting using the TOML file in this comprehensive guide. Enhance your setup today.

- Repository: [Xuan Zhang/OpenLogi](https://github.com/AprilNEA/OpenLogi)
- Tags: how-to-guide
- Published: 2026-08-21

---

**OpenLogi stores all Logitech device settings in a single TOML configuration file located at `~/.config/openlogi/config.toml`, which the Rust-based agent and GUI parse to apply DPI, bindings, and lighting changes.**

OpenLogi is an open-source input device manager for Logitech HID++ hardware. To configure OpenLogi for Logitech devices, you edit a central [`config.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/config.toml) file that defines DPI presets, button mappings, RGB lighting, and per-application overrides for each connected mouse or keyboard.

## Locating the Configuration File

OpenLogi follows the XDG Base Directory specification. The configuration file resides at `$XDG_CONFIG_HOME/openlogi/config.toml`, typically expanding to `~/.config/openlogi/config.toml` on macOS and Linux, or `%USERPROFILE%\.config\openlogi\config.toml` on Windows.

The core library resolves this path through the `paths::config_path()` function in [[`crates/openlogi-core/src/paths.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/paths.rs)](https://github.com/AprilNEA/OpenLogi/blob/master/crates/openlogi-core/src/paths.rs). Create the directory manually if it does not exist before placing your configuration file.

## Understanding the Configuration Schema

The configuration schema is strictly typed and enforced by Rust structs. Any syntax error or missing required field causes the GUI to enter read-only mode and prevents the agent from loading.

### Global Settings

Global application settings are defined by the `AppSettings` struct in [[`crates/openlogi-core/src/config/settings.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/config/settings.rs)](https://github.com/AprilNEA/OpenLogi/blob/master/crates/openlogi-core/src/config/settings.rs). This includes logging levels, default DPI behaviors, and global shortcut modifiers.

### Per-Device Configuration

Individual device configurations map to the `Device` struct in [[`crates/openlogi-core/src/config/device.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/config/device.rs)](https://github.com/AprilNEA/OpenLogi/blob/master/crates/openlogi-core/src/config/device.rs). Each device section supports:

- **DPI settings**: Current value and preset arrays
- **Bindings**: Button-to-action mappings using variants from [[`crates/openlogi-core/src/binding/action.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/binding/action.rs)](https://github.com/AprilNEA/OpenLogi/blob/master/crates/openlogi-core/src/binding/action.rs)
- **Lighting**: RGB configurations and effect modes
- **SmartShift**: Ratchet wheel sensitivity settings
- **Per-app bindings**: Context-specific overrides using bundle identifiers

For a human-readable reference, see [[`docs/CONFIGURATION.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/CONFIGURATION.md)](https://github.com/AprilNEA/OpenLogi/blob/master/docs/CONFIGURATION.md).

## Setting Up Your First Device

Before editing the configuration, identify your device's **physical key**—a unique identifier generated when the agent first discovers the hardware.

### Step 1: Identify Device Physical Keys

Use the CLI to list connected devices and their physical keys:

```bash
openlogi-cli list

```

This command, implemented in [[`crates/openlogi-cli/src/cmd/list.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-cli/src/cmd/list.rs)](https://github.com/AprilNEA/OpenLogi/blob/master/crates/openlogi-cli/src/cmd/list.rs), outputs identifiers in the format `receiver:12345:slot:1`.

### Step 2: Create the Configuration File

Copy the example template from the repository:

```bash
mkdir -p ~/.config/openlogi
cp docs/config.example.toml ~/.config/openlogi/config.toml

```

The template at [[`docs/config.example.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/config.example.toml)](https://github.com/AprilNEA/OpenLogi/blob/master/docs/config.example.toml) demonstrates the TOML structure validated against the Rust schemas.

## Configuring DPI, Bindings, and Lighting

Edit `~/.config/openlogi/config.toml` to define device-specific behaviors. Each device uses a TOML table named with its physical key.

### DPI Configuration

Set the default DPI and available presets:

```toml
[devices."receiver:12345:slot:1"]
enabled = true
dpi = 800
dpi_presets = [400, 800, 1600, 3200]

```

### Button Bindings

Map buttons to actions using enum variants:

```toml
[devices."receiver:12345:slot:1".bindings]
Button1 = "LeftClick"
Button2 = { Back = { CustomShortcut = "Cmd+Shift+P" } }
Button5 = "Copy"

```

### Per-Application Overrides

Define context-specific bindings using macOS bundle identifiers or executable names:

```toml
[devices."receiver:12345:slot:1".per_app_bindings."com.apple.Safari"]
Button3 = "Back"
Button4 = "Forward"

```

### Lighting Configuration

Control RGB lighting through the `Lighting` struct fields:

```toml
[devices."receiver:12345:slot:1".lighting]
mode = "Static"
color = { r = 255, g = 0, b = 0 }
brightness = 100

```

## Applying and Validating Changes

After editing the configuration, reload the agent to apply changes.

### Reloading the Configuration

If the agent is already running, trigger a reload without restarting:

```bash
openlogi-cli reload

```

The agent, as implemented in [[`crates/openlogi-agent/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent/src/main.rs)](https://github.com/AprilNEA/OpenLogi/blob/master/crates/openlogi-agent/src/main.rs), monitors for reload signals and re-parses the TOML file atomically.

### Validation and Error Handling

If the TOML contains syntax errors or invalid field values, the GUI entry point in [[`crates/openlogi-desktop/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-desktop/src/main.rs)](https://github.com/AprilNEA/OpenLogi/blob/master/crates/openlogi-desktop/src/main.rs) detects the parsing failure and enters read-only mode. The GUI displays the exact TOML error message, allowing you to fix the file and restart.

The system maintains five automatic backups (`config.toml.backup.1` through `config.toml.backup.5`) in the same directory, enabling recovery from corrupted configurations.

## Summary

Configuring OpenLogi for Logitech devices requires editing a single TOML file consumed by the entire application stack:

- **Location**: `$XDG_CONFIG_HOME/openlogi/config.toml` (resolved via `paths::config_path()`)
- **Schema**: Strictly defined in [`settings.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/settings.rs) and [`device.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/device.rs) with zero tolerance for malformed fields
- **Identification**: Use `openlogi-cli list` to discover device physical keys (e.g., `receiver:12345:slot:1`)
- **Capabilities**: Configure DPI presets, button bindings, lighting effects, SmartShift, and per-app overrides
- **Activation**: Run `openlogi-cli reload` to apply changes without restarting the agent
- **Safety**: Automatic backups (`config.toml.backup.{1..5}`) and validation prevent permanent configuration loss

## Frequently Asked Questions

### Where does OpenLogi store its configuration file?

OpenLogi stores settings in `$XDG_CONFIG_HOME/openlogi/config.toml`, defaulting to `~/.config/openlogi/config.toml` on Unix systems and `%USERPROFILE%\.config\openlogi\config.toml` on Windows. The `openlogi_core::paths::config_path()` function resolves this location at runtime according to the XDG Base Directory specification.

### What happens if I make a syntax error in config.toml?

The GUI will fail to parse the file and enter read-only mode, displaying the specific TOML error and line number. The agent continues running with the last valid configuration until you correct the syntax and trigger a reload. Five backup files are maintained automatically to prevent data loss from corruption.

### Can I configure different button mappings for different applications?

Yes. Use the `per_app_bindings` table within a device section, keyed by application bundle identifier on macOS or executable name on Linux/Windows. These bindings override the global `bindings` table when the specified application window is focused, enabling context-sensitive input behaviors.

### How do I find my device's physical key for the config file?

Run `openlogi-cli list` from your terminal. This outputs the physical key string (formatted as `receiver:<id>:slot:<n>`) for each connected Logitech device, which you must use as the TOML table header in your configuration file to target that specific hardware.