# How to Configure Custom Keyboard Shortcuts in OpenLogi's TOML Files > Learn to configure custom keyboard shortcuts in OpenLogi using TOML files. Define actions like Cmd+Shift+P and assign them to device bindings, app overrides, or global mappings. - Repository: [Xuan Zhang/OpenLogi](https://github.com/AprilNEA/OpenLogi) - Tags: how-to-guide - Published: 2026-09-12 --- **OpenLogi stores user configuration in plain TOML files where custom keyboard shortcuts are defined using the `CustomShortcut` variant of the `Action` enum, parsed as human-readable chords like `"Cmd+Shift+P"` and assigned to device bindings, per-app overrides, Action Ring slots, or global keyboard mappings.** OpenLogi is an open-source input management framework that translates mouse buttons and device inputs into system-level keyboard events. Understanding how **custom keyboard shortcuts configured in OpenLogi's TOML files** work allows you to inject complex key combinations directly from your hardware without application-level scripting. ## The CustomShortcut Action Type At the core of OpenLogi's shortcut system is the `Action` enum defined in [`crates/openlogi-core/src/binding/action.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/binding/action.rs). The **CustomShortcut** variant wraps a `KeyCombo` struct, representing a specific chord of modifier keys and a character key that the system will simulate when the action is triggered. When the TOML parser encounters a binding definition, it deserializes entries like `CustomShortcut = "Cmd+Shift+P"` into `Action::CustomShortcut(KeyCombo)`. This abstraction ensures that any input source—whether a mouse button, gesture, or another keyboard shortcut—can emit the same standardized key event through OpenLogi's injection layer. ## How KeyCombo Parses Shortcut Strings The human-readable chord syntax is handled by the `KeyCombo` parser located in [`crates/openlogi-core/src/binding/key_combo.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/binding/key_combo.rs). This module splits strings on the `+` delimiter to identify modifier flags and the final key code. Valid modifier tokens include **Cmd**, **Ctrl**, **Shift**, and **Option** (macOS nomenclature). The parser validates these against macOS key codes at configuration time, rejecting invalid combinations before the runtime injection phase begins. According to the AprilNEA/OpenLogi source code, Windows-specific key mappings are processed in separate platform layers rather than in the core TOML parsing logic. ## TOML Configuration Contexts for Shortcuts OpenLogi supports defining **custom keyboard shortcuts configured in OpenLogi's TOML files** across four distinct binding contexts. Each context determines which input triggers the simulated keystroke and under what conditions the action executes. ### Device-Level Bindings Device bindings attach shortcuts directly to physical controls on a specific mouse or input device. These mappings live under the `[devices."".bindings]` section and override default button behaviors. ```toml [devices."receiver:aabbccdd:slot:1".bindings] MiddleClick = { CustomShortcut = "Ctrl+Space" } ``` In this example, pressing the middle mouse button on the specified device injects a `Ctrl+Space` keystroke into the active application. ### Per-Application Overrides Per-app bindings allow the same physical button to emit different shortcuts depending on which application currently has focus. These tables use the syntax `[devices."".per_app_bindings.""]`. ```toml [devices."receiver:aabbccdd:slot:1".per_app_bindings."exe:sharex.exe"] MiddleClick = { CustomShortcut = "F1" } ``` This configuration maps the middle mouse button to the `F1` key exclusively when ShareX is the foreground window, reverting to default behavior in other contexts. ### Action Ring Integration The Action Ring provides a radial menu interface where each slot can trigger a custom shortcut. Slots are defined under `[devices."".action_ring.default.slots]` and require both an action and an icon specification. ```toml [devices."receiver:aabbccdd:slot:1".action_ring.default.slots] Right = { action = { CustomShortcut = "Cmd+Shift+P" }, icon = "Applications" } ``` Here, selecting the right slot from the Action Ring injects the `Cmd+Shift+P` chord, commonly used to open application launchers or command palettes. ### Global Keyboard Bindings Global bindings map key combinations on the physical keyboard itself to OpenLogi actions, independent of any mouse device. These reside in `[keyboard.bindings]` and reference action identifiers directly. ```toml [keyboard.bindings] "shift+command+f5" = "ShowDesktop" ``` While this example triggers the built-in `ShowDesktop` action, the same syntax supports any defined action within the OpenLogi system, including custom shortcuts when referenced by identifier. ## Complete Configuration Examples The repository includes a comprehensive reference at [`docs/config.example.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/config.example.toml) demonstrating production-ready patterns. Below are four distinct patterns for **custom keyboard shortcuts configured in OpenLogi's TOML files**: ```toml # 1. Assign a custom shortcut to the middle mouse button of a specific device [devices."receiver:aabbccdd:slot:1".bindings] MiddleClick = { CustomShortcut = "Ctrl+Space" } # 2. Override the same button only when ShareX is the active app [devices."receiver:aabbccdd:slot:1".per_app_bindings."exe:sharex.exe"] MiddleClick = { CustomShortcut = "F1" } # 3. Add a custom shortcut to the Action Ring (right slot) [devices."receiver:aabbccdd:slot:1".action_ring.default.slots] Right = { action = { CustomShortcut = "Cmd+Shift+P" }, icon = "Applications" } # 4. Define a global keyboard shortcut (Shift+Cmd+F5) that shows the desktop [keyboard.bindings] "shift+command+f5" = "ShowDesktop" ``` ## Implementation Deep Dive Several source files govern how TOML-defined shortcuts translate into system events: - **[`docs/config.example.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/config.example.toml)**: Provides the authoritative reference for valid TOML structures and nesting conventions. - **[`crates/openlogi-core/src/binding/action.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/binding/action.rs)**: Defines the `Action` enum including the `CustomShortcut` variant and its serialization logic. - **[`crates/openlogi-core/src/binding/key_combo.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/binding/key_combo.rs)**: Implements the parser for chord syntax and validates macOS key code compatibility. - **[`crates/openlogi-desktop/src/ui/action.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-desktop/src/ui/action.rs)**: Handles rendering of custom shortcut labels and icons in the graphical configuration interface. - **`crates/openlogi-inject/src/inject/*.rs`**: Contains platform-specific implementations for injecting the parsed key events into the operating system event queue. ## Summary - OpenLogi uses **TOML files** for user configuration, with shortcuts defined as `CustomShortcut` tables containing `KeyCombo` strings. - The **chord syntax** uses `+` to separate modifiers (Cmd, Ctrl, Shift, Option) from the final key, parsed by [`crates/openlogi-core/src/binding/key_combo.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/binding/key_combo.rs). - Shortcuts can be bound at the **device level**, **per-application**, within the **Action Ring**, or as **global keyboard** mappings. - The `Action::CustomShortcut` enum variant in [`crates/openlogi-core/src/binding/action.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/binding/action.rs) provides the runtime representation used across all binding types. - Platform-specific injection logic in the `openlogi-inject` crate translates these configurations into actual OS key events at runtime. ## Frequently Asked Questions ### What is the correct syntax for modifier keys in OpenLogi shortcuts? OpenLogi accepts **Cmd**, **Ctrl**, **Shift**, and **Option** as modifier tokens in the chord string. These must be separated by the `+` character and precede the final key code, as implemented in [`crates/openlogi-core/src/binding/key_combo.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/binding/key_combo.rs). For example, `"Cmd+Shift+P"` represents holding Command and Shift while pressing P. ### Can custom keyboard shortcuts be used on Windows, or are they macOS-only? While the `KeyCombo` parser in [`crates/openlogi-core/src/binding/key_combo.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/binding/key_combo.rs) validates macOS key codes during TOML parsing, the actual platform injection is handled in `crates/openlogi-inject/src/inject/*.rs`. This architecture allows Windows-specific mappings to be processed separately, though the TOML configuration syntax remains identical across platforms. ### Where should I define a shortcut that needs to work everywhere versus only in specific apps? Use **`[keyboard.bindings]`** for global shortcuts that should trigger regardless of input device or application focus. Use **`[devices."".bindings]`** for hardware-specific mappings, and **`[devices."".per_app_bindings.""]`** for context-sensitive overrides that only apply when a specific application is focused. ### How does OpenLogi validate that my shortcut string is valid? Validation occurs at configuration load time in [`crates/openlogi-core/src/binding/key_combo.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/binding/key_combo.rs). The parser attempts to resolve the chord string into a `KeyCombo` struct containing modifier flags and a key code. If the syntax is malformed or contains invalid key names, the TOML parser will fail during initialization, preventing runtime errors in the injection layer.