# How to Remap Buttons on Logitech Devices with OpenLogi: A Complete Guide

> Easily remap Logitech mouse buttons with OpenLogi. This guide shows you how to customize actions via TOML, CLI, or GUI for personalized control.

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

---

**OpenLogi remaps Logitech mouse buttons through a TOML configuration file, CLI commands, or a GUI application, converting physical button events into logical `ButtonId` values that trigger customizable actions ranging from keystrokes to application launches.**

OpenLogi is an open-source tool that enables advanced button remapping for Logitech peripherals on desktop systems. Whether you want to bind the Back button to a browser navigation command or transform the middle click into a custom shortcut, OpenLogi provides multiple interfaces to remap buttons on Logitech devices with precise control over the input pipeline.

## Configuring Button Remaps via TOML

OpenLogi stores per-device bindings in a plain-text TOML file located at `~/.config/openlogi/config.toml`. Each device entry contains a `bindings` table that maps a `ButtonId` to an `Action`, as defined in the repository's configuration schema.

To remap buttons, locate your device section (identified by receiver ID and slot) and modify the `bindings` table:

```toml
[devices."receiver:12345678:slot:1"]
enabled = true
dpi = 800
bindings = {
    Back    = "BrowserBack",
    Forward = { CustomShortcut = "Cmd+Shift+P" },
    MiddleClick = { OpenApplication = { path = "~/Downloads", display_name = "Downloads" } }
}

```

The configuration supports multiple action types including simple clicks, custom shortcuts, and application launches. Changes to this file trigger an immediate reload of the agent, ensuring your mappings apply without restarting the application.

## Remapping via the CLI

The `openlogi-cli` crate provides scriptable control over button mappings. Located at [`crates/openlogi-cli/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-cli/src/main.rs), the CLI implements `list` and `set-binding` commands for device management.

First, identify your device:

```bash
openlogi-cli list

```

Then apply a binding:

```bash
openlogi-cli set-binding \
  --device "receiver:12345678:slot:1" \
  --button Back \
  --action BrowserBack

```

This command updates the underlying TOML configuration and signals the agent to reload, providing a programmatic alternative to manual file editing.

## Programmatic Remapping with Rust

For custom tooling, OpenLogi's Rust API exposes direct binding manipulation through the `DesktopState` struct in [`crates/openlogi-desktop/src/state/bindings.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-desktop/src/state/bindings.rs).

```rust
use openlogi_core::binding::{ButtonId, Action};
use openlogi_desktop::state::DesktopState;

// Assume `state` is a mutable reference to the running DesktopState
let device_key = "receiver:12345678:slot:1";
state
    .config
    .set_binding(device_key, ButtonId::Back, Action::BrowserBack);
state.persist_and_reload("binding");

```

The `set_binding` method updates the in-memory configuration, while `persist_and_reload` writes the change to disk and notifies the agent. This approach is useful for building custom automation tools that dynamically adjust mappings based on context.

## Remapping via the GUI

The OpenLogi desktop application provides a visual interface for button remapping. The GUI writes atomically to the configuration file and maintains backup copies to prevent data loss.

To remap a button using the GUI:

1. Open the OpenLogi desktop app and select your Logitech mouse from the device list.
2. Navigate to the **Bindings** tab and locate the button identifier (e.g., **MiddleClick**).
3. Select the desired action type, such as **OpenApplication** or **CustomShortcut**.
4. Fill in the required parameters (e.g., path `~/Downloads` for an application launch).
5. Click **Save** to write the changes to [`config.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/config.toml) and apply them immediately via the IPC mechanism in [`crates/openlogi-ipc/src/ipc.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-ipc/src/ipc.rs).

## Understanding the Remapping Pipeline

Under the hood, OpenLogi implements button remapping through a layered architecture that enforces Logitech device specificity and logical button abstraction.

### Device Detection and Filtering

The hook subsystem in `crates/openlogi-hook` receives raw mouse events from the operating system. Only Logitech devices are considered remappable, enforced by the `source_is_remappable` function in [`crates/openlogi-hook/src/lib.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-hook/src/lib.rs) (lines 90-101). This ensures the remapping logic only processes events from supported hardware.

### Logical Button Resolution

All button identifiers are unified under the `ButtonId` enum defined in [`crates/openlogi-core/src/binding/button.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/binding/button.rs). This enum includes variants such as `LeftClick`, `RightClick`, `MiddleClick`, `Back`, `Forward`, and `DpiToggle`.

When the agent receives a button event, the `bindings_for_current` function in [`crates/openlogi-desktop/src/state/bindings.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-desktop/src/state/bindings.rs) (lines 102-108) looks up the current device's bindings map. The system then dispatches the associated action to the inject subsystem, which synthesizes the appropriate mouse or keyboard event at the OS level.

### Persistence and Live Reload

The configuration system supports atomic writes and live reloading. When you edit the TOML file or use the GUI/CLI, the agent reloads the configuration instantly without requiring a restart. The GUI specifically writes atomically and maintains backup copies to ensure configuration integrity.

## Summary

- OpenLogi stores button mappings in `~/.config/openlogi/config.toml` using a TOML structure that maps `ButtonId` values to `Action` types.
- The CLI (`openlogi-cli`) provides `list` and `set-binding` commands for scriptable remapping of Logitech devices.
- The Rust API exposes `set_binding` and `persist_and_reload` methods in `DesktopState` for programmatic control.
- Only Logitech devices pass the `source_is_remappable` filter in the hook subsystem, ensuring targeted remapping.
- Changes apply immediately through the IPC transport system without requiring agent restarts.

## Frequently Asked Questions

### Where is the OpenLogi configuration file stored?

The default location is `~/.config/openlogi/config.toml` on Unix-like systems. This plain-text TOML file contains per-device settings including DPI values and button `bindings` tables. You can edit this file manually or through the GUI/CLI interfaces.

### Can I remap buttons on non-Logitech mice?

No. The hook subsystem in [`crates/openlogi-hook/src/lib.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-hook/src/lib.rs) specifically filters for Logitech devices using the `source_is_remappable` function (lines 90-101). Only hardware identified as Logitech peripherals will trigger the remapping logic.

### Do I need to restart the agent after changing button mappings?

No. OpenLogi supports live configuration reloading. When you modify the TOML file or use the GUI/CLI to update bindings, the agent detects the change and applies it immediately via the IPC transport mechanism in [`crates/openlogi-ipc/src/ipc.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-ipc/src/ipc.rs).

### What button actions are supported besides mouse clicks?

OpenLogi supports several action types defined in the core crate: `BrowserBack`, `BrowserForward`, `CustomShortcut` (for key combinations), `OpenApplication` (to launch programs), and standard mouse events like `LeftClick` or `MiddleClick`. The full schema is documented in [`docs/CONFIGURATION.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/CONFIGURATION.md).