How to Configure Global Keyboard Bindings in OpenLogi: A Complete Guide

OpenLogi stores global keyboard shortcuts in a platform-specific TOML configuration file that is hot-reloaded by the background agent and synchronized to Logitech HID++ devices in real-time.

OpenLogi is an open-source utility for customizing Logitech input devices. This guide explains how to configure global keyboard bindings in OpenLogi by editing the TOML configuration file or using the GUI, with technical details derived from the AprilNEA/OpenLogi source code.

Understanding the Configuration Architecture

OpenLogi uses a modular architecture where configuration logic resides in the core crate while runtime execution happens in the agent. The binding definitions are implemented in crates/openlogi-core/src/binding.rs, which exposes the Action enum (variants like Copy, PlayPause, and ShowActionsRing) and the KeyCombo struct for parsing shortcut strings.

The configuration schema is defined in crates/openlogi-core/src/config.rs using Serde derive macros. This file establishes the [keyboard] table containing a bindings sub-table that deserializes into a HashMap<KeyCombo, Action>. At runtime, crates/openlogi-agent-core/src/orchestrator.rs monitors this configuration file for changes and dispatches updates to the HID++ write layer in crates/openlogi-hid/src/write/key_combo.rs.

Locating the Configuration File

OpenLogi stores user settings in a plain TOML file accessible by both the GUI and CLI. The file path depends on your operating system:

• Linux: ~/.config/openlogi/config.toml
• macOS: ~/Library/Application Support/openlogi/config.toml
• Windows: %APPDATA%\openlogi\config.toml

Both the GUI preferences pane and the openlogi CLI tool (crates/openlogi/src/main.rs) read from this single source of truth, ensuring consistency across interfaces.

Defining Keyboard Bindings in TOML

Global bindings are defined under the [keyboard.bindings] table in your config.toml. Each entry maps a key-combo string to an action name (the exact Rust enum variant from Action).

OpenLogi supports the following modifier aliases as implemented in the KeyCombo parser:

• Shift: shift
• Control: control, ctrl
• Option/Alt: option, alt
• Command: command, cmd

Here is a complete configuration example:

[keyboard.bindings]

# Simple shortcut to copy the current selection

Copy = "Cmd+C"

# Open the user's Downloads folder (custom shortcut)

OpenDownloads = { OpenApplication = { path = "~/Downloads", display_name = "Downloads" } }

# Show the Actions Ring – a global UI overlay

ShowRing = "Ctrl+Option+Space"

# Override the media play/pause key

PlayPause = "F8"

The left-hand side represents the action name, while the right-hand side is either a plain string parsed into a KeyCombo or an inline table when the action requires additional parameters (such as OpenApplication).

How Changes Are Applied at Runtime

When you save the config.toml file, the following sequence occurs:

1. Atomic Write: The GUI updates the on-disk TOML atomically while preserving comments and formatting.
2. File Watch: The agent core in crates/openlogi-agent-core/src/orchestrator.rs detects the filesystem change and triggers a configuration reload.
3. Validation: If the file contains syntax errors, the GUI refuses to overwrite it and displays a readable error message, preventing the agent from loading corrupted configuration.
4. Device Programming: The agent translates the KeyCombo → Action map into HID++ commands and pushes the new mapping to the connected Logitech device via crates/openlogi-hid/src/write/key_combo.rs.

To verify your current configuration from the command line, run:

openlogi list --show-config

Changes made directly to the file are picked up immediately by the agent without requiring a restart.

Summary

• OpenLogi stores global keyboard bindings in a TOML file under the [keyboard.bindings] section.
• The configuration schema is defined in crates/openlogi-core/src/config.rs and parsed using Serde.
• Supported modifiers include ctrl, alt, cmd, and shift with multiple alias options.
• The background agent in crates/openlogi-agent-core/src/orchestrator.rs hot-reloads configuration changes and updates HID++ devices in real-time.
• Both the GUI and CLI (crates/openlogi/src/main.rs) share the same configuration file for consistency.

Frequently Asked Questions

Where does OpenLogi store the global keyboard configuration?

OpenLogi stores the configuration in a platform-specific directory under a file named config.toml. On Linux, this is typically ~/.config/openlogi/config.toml; on macOS, ~/Library/Application Support/openlogi/config.toml; and on Windows, %APPDATA%\openlogi\config.toml.

What modifier keys are supported in OpenLogi key combinations?

According to the KeyCombo parser in crates/openlogi-core/src/binding.rs, OpenLogi supports shift, control (or ctrl), option (or alt), and command (or cmd). These can be combined with function keys (e.g., F8) or alphanumeric keys using plus signs as separators.

Do I need to restart OpenLogi after changing keyboard bindings?

No. The agent core monitors the configuration file for changes and reloads the binding map automatically. The new mappings are pushed to the connected Logitech device immediately via the HID++ protocol. However, if the TOML syntax is invalid, the GUI will reject the change and preserve your previous working configuration.

Can I define custom actions with parameters in the bindings table?

Yes. While simple actions use a key-combo string on the right-hand side, complex actions that require parameters (such as opening a specific application) use inline TOML tables. For example, OpenDownloads = { OpenApplication = { path = "~/Downloads", display_name = "Downloads" } } passes structured data to the OpenApplication action variant.

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