Configuration

Reference for the TOML config file — location, schema, all keys, actions, and gesture bindings.

OpenLogi stores everything in a single TOML file. The GUI writes it for you — the main window edits button and gesture bindings, DPI presets, SmartShift, and lighting, and the Settings window (⌘,) covers the app-wide preferences — but the file is plain text and safe to hand-edit. Per-app profile overlays have no dedicated editor yet, so those are authored here directly.

OpenLogi reads the config on startup and rewrites it atomically on every change. Hand-edit it while the app is quit, or the GUI will overwrite your edits the next time it saves.

File location

Platform	Path
macOS / Linux	`$XDG_CONFIG_HOME/openlogi/config.toml` (default `~/.config/openlogi/config.toml`)
Windows	`%USERPROFILE%\.config\openlogi\config.toml`

The file is written atomically (temp file + rename) and, on Unix, with 0600 permissions.

Top-level layout

schema_version = 2            # required; an unknown version is refused
selected_device = "2b042"     # HID++ key of the device shown in the carousel

[app_settings]                # app-wide preferences (omitted entirely when default)
# …

[devices.2b042]               # one block per device, keyed by HID++ id
# …

schema_version — the layout version (currently 2). A v1 file (separate button_bindings / gesture_bindings tables) still loads and is migrated to the unified bindings map on the next save; a file with an unrecognised version is refused rather than silently misread.
selected_device — remembers which device the carousel was on; omitted when unset.
[app_settings] — see below; the whole block is omitted while every field is at its default.
[devices.<key>] — per-device settings, keyed by each device's HID++ identifier (e.g. 2b042 for an MX Master 4).

`[app_settings]`

Key	Default	Meaning
`launch_at_login`	`false`	Start OpenLogi on login — a LaunchAgent plist on macOS, a systemd user unit on Linux.
`check_for_updates`	`false`	Opt-in. One `HEAD` request to the GitHub latest-release per launch; logs whether a newer version exists — never downloads. Off by default to keep no telemetry.
`show_in_menu_bar`	`true`	macOS only. `true` → menu-bar status item (no Dock icon while closed); `false` → ordinary Dock app.
`language`	(follow system)	UI locale, one of the 20 bundled locales (`en`, `de`, `pt-BR`, `zh-CN`, …). Unset follows the system locale.
`thumbwheel_sensitivity`	`14`	Thumb-wheel responsiveness on a `1`–`100` scale; the default is 1× native scroll (the wheel is only diverted from native scrolling once this leaves the default).

Per-device blocks

Each [devices.<key>] block holds the settings for one physical device. The key is the device's HID++ identifier — the same config_key the GUI uses.

Key	Type	Meaning
`bindings`	table	Maps a logical button to a binding: a single action, or a per-direction gesture table (see Buttons and Gesture bindings).
`per_app_bindings`	table of tables	Overlays keyed by app id (e.g. `"com.microsoft.VSCode"`). When that app is frontmost its entries win; everything else falls through to `bindings`.
`gesture_owner`	string	Which button owns the gesture role: a button name or `"Off"`. Absent means "infer" — the thumb pad owns gestures when present.
`dpi_presets`	array of ints	Ordered DPI values cycled by `CycleDpiPresets` and indexed by `SetDpiPreset`.
`lighting`	table	Per-device RGB for wired G-series keyboards — see below.

`lighting`

Key	Default	Meaning
`enabled`	`true`	Whether the static color is applied.
`color`	`"ffffff"`	Static color as six hex digits `RRGGBB` (no leading `#`).
`brightness`	`100`	`0`–`100`; clamped on load.

Buttons

bindings and per_app_bindings are keyed by a logical button:

LeftClick, RightClick, MiddleClick, Back, Forward, DpiToggle (the mode-shift button under the wheel), Thumbwheel (its click), ThumbwheelScrollUp, ThumbwheelScrollDown, GestureButton.

Actions

Binding values are action names, written verbatim:

Suppress — None (capture the input but do nothing)
Mouse — LeftClick, RightClick, MiddleClick, MouseBack, MouseForward (the real extra-button events most apps treat as native back/forward)
Editing — Copy, Paste, Cut, Undo, Redo, SelectAll, Find, Save
Browser & tabs — BrowserBack, BrowserForward, NewTab, CloseTab, ReopenTab, NextTab, PrevTab, ReloadPage
Window & desktop (macOS) — MissionControl, AppExpose, PreviousDesktop, NextDesktop, ShowDesktop, LaunchpadShow
System — LockScreen, Screenshot
Media — PlayPause, NextTrack, PrevTrack, VolumeUp, VolumeDown, MuteVolume
DPI & wheel — CycleDpiPresets, SetDpiPreset, ToggleSmartShift
Scroll — ScrollUp, ScrollDown, HorizontalScrollLeft, HorizontalScrollRight
Custom — CustomShortcut, a recorded key chord

SetDpiPreset (a preset index) and CustomShortcut (a recorded chord) carry extra data, so they're best set from the GUI's action picker rather than by hand.

Gesture bindings

A button in gesture mode binds per direction instead of to a single action: its bindings entry becomes a sub-table keyed by Up, Down, Left, Right, Click (Click is the plain press, no swipe). Which button that is — the thumb pad, or another capable button — is chosen via gesture_owner or the GUI's gesture-button selector.

Example

schema_version = 2
selected_device = "2b042"

[app_settings]
launch_at_login = true
language = "zh-CN"
thumbwheel_sensitivity = 14

# MX Master 4 (HID++ key 2b042)
[devices.2b042]
gesture_owner = "GestureButton"
dpi_presets = [800, 1600, 3200]

[devices.2b042.bindings]
Back = "BrowserBack"
Forward = "BrowserForward"
MiddleClick = "MissionControl"

# The gesture button binds per direction; Click is the plain press.
[devices.2b042.bindings.GestureButton]
Left = "PrevTab"
Right = "NextTab"
Click = "PlayPause"

# Back becomes Undo only while VS Code is frontmost.
[devices.2b042.per_app_bindings."com.microsoft.VSCode"]
Back = "Undo"

# A wired G-series keyboard, under its own HID++ device key
# (`g513` here stands in for that key).
[devices.g513.lighting]
enabled = true
color = "ff0000"
brightness = 80

Source: CONFIGURATION.md

On this page