How to Configure OpenLogi for Logitech Devices: Complete TOML Guide

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

openlogi-cli list

This command, implemented in [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:

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

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

Button Bindings

Map buttons to actions using enum variants:

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

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

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

openlogi-cli reload

The agent, as implemented in [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/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 and 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}