How to Configure OpenLogi Button Mappings: A Complete TOML Guide

OpenLogi stores button mappings in a plain-text TOML configuration file where each profile defines application-specific or global behaviors using the [profiles.<name>.buttons.<id>] syntax with action and optional params fields.

OpenLogi is an open-source Logitech device management tool that replaces proprietary software with a flat-file configuration approach. Learning how to configure OpenLogi button mappings allows you to remap side buttons, DPI toggles, and scroll wheels to custom actions or macros without vendor lock-in. All settings reside in a single TOML file that the agent monitors for changes.

Understanding the Configuration Structure

OpenLogi uses a profile-based architecture defined in docs/CONFIGURATION.md. Each profile corresponds to either a specific executable or a global catch-all, allowing contextual button behavior that switches automatically based on the active window.

The profiles Table

Configuration files are organized into profiles under the top-level [profiles] namespace. The special "default" profile acts as a fallback when no application-specific mapping exists. According to the implementation in [crates/openlogi-core/src/config.rs](https://github.com/AprilNEA/OpenLogi/blob/master/crates/openlogi-core/src/config.rs), the parser expects the following hierarchy:

[profiles.<profile_name>]

# Per-profile settings like DPI

[profiles.<profile_name>.buttons.<button_id>]
action = "<action_name>"
params = { key = "value" }

• <profile_name> — String identifier. Use "default" for global settings, or "app.exe" for per-application mappings.
• <button_id> — Numeric identifier as reported by the HID device (e.g., 1 for the first side button).

Button Identifiers

Physical buttons are referenced by integer IDs. While these vary by Logitech model, standard MX Master series devices typically map side buttons to low integers. The configuration parser validates these IDs against available hardware inputs defined in the core library.

Defining Button Actions

Every button mapping requires an action field and optionally accepts a params table for customization. Supported actions include scroll, dpi_up, dpi_down, smartshift_toggle, and macro.

Basic Syntax

The minimal configuration binds a button to a built-in action:

[profiles.default.buttons.1]
action = "scroll"

This assigns the scroll action to button 1 in the default profile.

Action Parameters

Complex actions accept structured parameters. For example, scroll speed adjustments use the speed key, while macros require a keys array. The full schema is documented in [docs/CONFIGURATION.md](https://github.com/AprilNEA/OpenLogi/blob/master/docs/CONFIGURATION.md) and enforced by the deserialization logic in [crates/openlogi-core/src/config.rs](https://github.com/AprilNEA/OpenLogi/blob/master/crates/openlogi-core/src/config.rs).

[profiles.default.buttons.1]
action = "scroll"
params = { speed = 3 }

Practical Configuration Examples

Real-world setups often require mixing global defaults with application-specific overrides. The agent loads these definitions at startup and monitors the file for changes.

Example 1: Global Scroll Mapping

Map the first side button to a fast scroll action across all applications:

[profiles.default.buttons.1]
action = "scroll"
params = { speed = 3 }

Example 2: Per-Application DPI Control

Assign DPI-up functionality to button 2 only when Photoshop is active:

[profiles."photoshop.exe".buttons.2]
action = "dpi_up"

Example 3: Complex Macro Binding

Bind a keystroke sequence to button 3 using the macro action with inline array syntax:

[profiles.default.buttons.3]
action = "macro"
params = { keys = ["Ctrl", "Alt", "M"] }

Configuration Reload and File Location

Place your configuration file at ~/.config/openlogi/config.toml (Linux) or the platform-appropriate equivalent. As implemented in [crates/openlogi-agent/src/main.rs](https://github.com/AprilNEA/OpenLogi/blob/master/crates/openlogi-agent/src/main.rs), the agent automatically reloads the configuration when the file changes on disk. Alternatively, force an immediate reload by running:

openlogi reload

For a complete reference implementation, see [docs/config.example.toml](https://github.com/AprilNEA/OpenLogi/blob/master/docs/config.example.toml) in the repository.

Summary

• Configuration format: Plain-text TOML file located at ~/.config/openlogi/config.toml
• Profile syntax: Use [profiles.<name>.buttons.<id>] to define mappings
• Required fields: Each button requires an action string
• Optional fields: Use params tables to pass action-specific arguments like speed or keys
• Reload behavior: Changes apply automatically or via openlogi reload as handled by the agent entry point
• Source references: Parsing logic lives in crates/openlogi-core/src/config.rs with runtime loading in crates/openlogi-agent/src/main.rs

Frequently Asked Questions

Where does OpenLogi look for the configuration file?

By default, OpenLogi searches for config.toml in the platform-specific user configuration directory, typically ~/.config/openlogi/ on Linux systems. You can verify the exact path and loading behavior by examining the initialization sequence in [crates/openlogi-agent/src/main.rs](https://github.com/AprilNEA/OpenLogi/blob/master/crates/openlogi-agent/src/main.rs).

How do I find the numeric button ID for my mouse?

Button IDs correspond to the HID usage indices reported by your specific Logitech device. While the core configuration parser in [crates/openlogi-core/src/config.rs](https://github.com/AprilNEA/OpenLogi/blob/master/crates/openlogi-core/src/config.rs) accepts any integer, you should consult your device's technical specifications or use a HID debugging tool to identify the correct index for physical buttons.

Can I share button mappings across all applications?

Yes. Define bindings under the [profiles.default] section to create global mappings. These apply whenever the active window does not match a specific application profile. The default profile serves as the fallback layer in the hierarchy described in [docs/CONFIGURATION.md](https://github.com/AprilNEA/OpenLogi/blob/master/docs/CONFIGURATION.md).

What actions are supported besides scroll and DPI controls?

OpenLogi supports smartshift_toggle, macro, and any custom actions defined in the actions table of your configuration. The full list of built-in identifiers and their parameter schemas is documented in the project's configuration specification.

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