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

> Learn how to configure global keyboard bindings in OpenLogi with this complete guide. Discover how to use TOML files for hot-reloaded shortcuts synchronized to your Logitech devices.

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

---

**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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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:

```toml
[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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-hid/src/write/key_combo.rs).

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

```bash
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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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.