Command line
Use the OpenLogi command line to inspect hardware, run diagnostics, and automate supported settings through a local JSON API.
OpenLogi v0.8.15 provides human-readable hardware commands and a versioned JSON API. Most hardware commands can access devices directly. openlogi backlight and the openlogi api commands use only a running OpenLogi agent.
Run the command
Run openlogi --help to inspect the installed command tree. See Installation for package and source-build instructions.
openlogi without a subcommand runs openlogi list. The command lists connected receivers, paired HID++ devices, and Logitech webcams. It uses the running agent's inventory when possible, then falls back to direct hardware enumeration. A completed scan with no devices or webcams exits with status 2.
| Command | Result |
|---|---|
openlogi or openlogi list | List receivers, paired HID++ devices, and Logitech webcams. |
openlogi assets sync | Download assets for the local bundle. |
openlogi --help | Print command and option help. |
openlogi --version | Print the CLI version. |
Synchronize assets
openlogi assets sync races the automatic asset mirrors. The first mirror with a valid catalog supplies every file for that synchronization run. The command skips unchanged files by SHA-256 and removes asset depots absent from the catalog.
Use --base URL or OPENLOGI_ASSETS to use one asset origin instead. --out DIR changes the destination directory.
openlogi assets sync
openlogi assets sync --base https://assets.example.invalid
OPENLOGI_ASSETS=https://assets.example.invalid openlogi assets syncSet the log filter
OPENLOGI_LOG sets the tracing filter for the CLI, desktop app, and agent. It accepts EnvFilter directives and defaults to info when unset. Logs go to stderr, so JSON API output stays on stdout.
OPENLOGI_LOG=debug openlogi list
OPENLOGI_LOG=hidpp=trace,openlogi_agent=debug openlogi api statusHardware commands
The following commands access hardware outside the JSON API. Most commands select the first compatible device when they can. Use the --device or --camera selector when more than one device matches. openlogi backlight uses stricter rules; see Keyboard backlight.
| Command | Purpose |
|---|---|
openlogi backlight [--device NAME] | Read a keyboard's HID++ 0x1982 backlight state. |
openlogi backlight [--device NAME] [status|off|on|auto on|auto off|level N|battery-saving on|battery-saving off] | Persistently change a supported keyboard backlight control. |
openlogi snapshot [PATH] [--camera ID] | Capture one Logitech webcam frame to a PNG. The default path is snapshot.png. |
openlogi camera [--camera ID] [get] | Show UVC control ranges and current values for a Logitech webcam. |
openlogi camera [--camera ID] set CONTROL VALUE | Write a listed UVC image control or an automatic-control toggle. |
openlogi light list | List supported standalone lights and their controls. |
openlogi light status|on|off [--device NAME] | Read or change one standalone light. |
openlogi light brightness --percent 0..100|--lumens N [--device NAME] | Set normalized brightness or native lumens. |
openlogi light temperature --kelvin N [--device NAME] | Set colour temperature. |
openlogi fixture contribute | Build a privacy-safe fixture through a resumable wizard. |
openlogi fixture record case|profile | Capture a named read or agent semantic state for a fixture. |
openlogi fixture verify | Strictly verify a complete fixture directory. |
camera set accepts these control names: zoom, pan, tilt, focus, exposure, power_line_frequency, low_light_compensation, brightness, contrast, saturation, sharpness, gain, backlight_compensation, white_balance, tint, focus_auto, exposure_auto, and white_balance_auto.
Hardware commands can change device state. The fixture commands are maintainer tooling. Direct fixture discovery can enable receiver notifications, and it does not restore those flags.
Keyboard backlight
openlogi backlight sends every read and change through the running OpenLogi agent. The agent must use the same OPENLOGI_PROFILE as the CLI and accept the CLI's protocol version. The command does not open the keyboard directly and does not start the agent. If no compatible agent answers, the command stops with an error.
The command selects a keyboard from the agent's device inventory:
--device NAMEmatches a case-insensitive part of the device name. The text must match exactly one online HID++ device.- Without
--device, exactly one online device must have measured backlight support. If the agent has not measured a keyboard's support yet, select that keyboard with--device. - The command stops before any read or write when the inventory is not ready, the device has no agent route, or the selection is ambiguous. It also rejects a device that is known to have no backlight support.
The agent writes the keyboard and reads the state back. The CLI reports success only after it prints that read-back, and an open Backlight card in the desktop app shows the new state. If the agent times out or disconnects during a change, the result is unconfirmed. The command does not retry. Run openlogi backlight status before you send the change again.
This behavior applies to builds after v0.8.17. Earlier versions opened the keyboard directly when no agent ran, and they selected the first matching device.
Hardware diagnostics
openlogi diag runs direct HID++ diagnostics. It does not update config.toml or use the desktop app. On macOS, a diagnostic command requests Input Monitoring for the CLI binary before it opens a device.
| Command | Behavior |
|---|---|
diag features | Dump each online HID++ device's feature table and firmware entities. |
diag controls [--device NAME] | Dump HID++ 0x1b04 reprogrammable controls and capability flags. |
diag battery [--device NAME] | Print the raw battery report from 0x1004, 0x1000, or 0x1F20. |
diag dpi [--target DPI] [--device NAME] | Read DPI, write a test value, read it back, and restore the original value. |
diag pointer-speed [--target RAW] [--device NAME] | Test HID++ 0x2205 pointer motion scaling, then attempt restoration. |
diag smartshift [--leave-flipped|--sensitivity N|--torque PERCENT] [--device NAME] | Toggle SmartShift, set its release threshold, or set wheel torque. |
diag lighting RRGGBB [--device NAME] [--method auto|effects|perkey|perkeyv2] | Set an online RGB device to one solid colour. |
diag wheel [--resolution low|high] [--device NAME] | Read or set HID++ 0x2121 wheel reporting resolution. |
The diagnostic commands are for verified write paths, not routine preference changes. diag dpi restores after a successful test. Plain diag smartshift restores its original mode unless --leave-flipped is present. Other diagnostic writes can remain on the device.
Test pointer motion scaling
diag pointer-speed tests HID++ 0x2205 pointer motion scaling. --device NAME selects a case-insensitive name substring. --target RAW accepts a non-zero raw 8.8 fixed-point value, where 256 is 1×.
Without --target, the command halves the current raw value. If the current value is 1, it doubles that value instead. Firmware can accept extreme values without clipping.
The diagnostic writes the test value, then attempts to restore and verify the original value before it judges the test write. It also attempts restoration if the test write fails. A restoration error means OpenLogi could not confirm the original scaling.
Test SmartShift torque
diag smartshift --torque PERCENT writes a wheel-feedback intensity from 1 through 100. It is available only when the device advertises HID++ 0x2111 TUNABLE_TORQUE. The command preserves the current SmartShift mode and automatic-release threshold.
--sensitivity N accepts 1 through 255. Values 1 through 254 set the automatic-release threshold. Value 255 selects permanent ratchet mode when the wheel is already in ratchet mode. --leave-flipped, --sensitivity, and --torque are mutually exclusive where indicated by the command help.
JSON automation API
openlogi api is a local JSON interface for scripts and launchers. It requires a running, protocol-compatible OpenLogi agent. It never starts the agent, opens hardware directly, or falls back to diagnostic commands.
Prerequisites
Start OpenLogi normally before calling the API. Use matching CLI and agent builds when the API returns version_mismatch.
Run openlogi api devices first. Copy one exact, non-null id and pass it as one quoted --device value. Device operations require inventory: "ready"; only a ready, empty devices array means no peripherals were found.
openlogi api status
openlogi api devices
openlogi api dpi --device "$DEVICE_ID"Commands and response fields
Every successful command puts the fields below in data. A null measured value means that the agent has no measured value. The API does not include cameras.
| Command | data fields |
|---|---|
status | agent_version, inventory, accessibility_granted, input_monitoring_granted, hook_installed, hid_open_failures, launch_at_login, virtual_keyboard |
devices | inventory; devices, an array of id, name, kind, online, battery, capabilities, and light_capabilities |
dpi --device ID [--set DPI] | device, persistence, current, supported |
smartshift --device ID [--mode free|ratchet] [--auto-disengage N] | device, persistence, mode, auto_disengage, tunable_torque |
fn-lock --device ID [--set on|off] | device, persistence, fn_lock, default_fn_lock |
os-layout --device ID --set on|off --save | device, persistence, keep_os_layout |
report-rate --device ID [--set HZ] | device, persistence, current, supported |
easy-switch --device ID [--channel N --name TEXT] | device, persistence, current_channel, can_rename, channels |
status.virtual_keyboard is active when the agent types synthesized keys on the macOS virtual HID keyboard, unavailable when macOS posts them as software key events, and unsupported on Windows and Linux. Agents before 0.8.17 do not report it.
smartshift.tunable_torque is a 1–100 percentage of the wheel's maximum force, or null. fn-lock.default_fn_lock is a boolean or null. Report-rate values are hertz and apply to the current connection. See Report rate.
Each easy-switch.channels entry has channel, paired, connection, name, name_max_len, and os. Channels start at 1. The connection value is unknown, unifying, usb, bluetooth, or bolt. See Easy-Switch.
Change settings
Read commands do not write hardware. Add the setting flag to make an immediate change.
openlogi api dpi --device "$DEVICE_ID" --set 1200
openlogi api smartshift --device "$DEVICE_ID" --mode free
openlogi api smartshift --device "$DEVICE_ID" --mode ratchet --auto-disengage 255
openlogi api fn-lock --device "$DEVICE_ID" --set on
openlogi api os-layout --device "$DEVICE_ID" --set on --save
openlogi api report-rate --device "$DEVICE_ID" --set 1000 --save
openlogi api easy-switch --device "$DEVICE_ID" --channel 2 --name "Work laptop"A DPI value must occur in supported. OpenLogi rejects other values without rounding. A report rate must occur in the rate list for the current connection.
SmartShift preserves fields that the command omits. auto_disengage accepts 1 through 254, or 255 for permanent ratchet. Use --mode ratchet --auto-disengage 255 to disable automatic release. With --save, the SmartShift threshold must be 8 through 255.
fn-lock --set on makes bare function keys send F1 through F12. off uses their printed media functions. os-layout is an agent setting, so it requires both --set and --save. With on, the agent keeps a compatible keyboard on the host OS layout. With off, OpenLogi leaves the keyboard layout unchanged.
An Easy-Switch rename requires both --channel and --name. The name is trimmed before it is written. The device stores the name, so Easy-Switch rejects --save and always returns persistence: "not_saved".
Save preferences
Add --save to an explicit DPI, SmartShift, Fn-lock, or report-rate change to save the verified setting in config.toml. Saving requires a probed physical device identity. OpenLogi never uses the API route ID as a configuration key.
A save edits only the selected setting and preserves unrelated preferences and comments. A per-link DPI or SmartShift override causes link_override instead of saving a device default that the override would supersede. See Configuration for the complete file reference.
Hardware writes, configuration saves, and agent reloads are separate steps. A later failure does not undo a hardware write. On a save error, error.persistence: "not_saved" means that OpenLogi did not save the file. error.persistence: "saved" means that it saved the file, but reload failed or its result is unknown.
JSON envelope and exit codes
After argument parsing, each API invocation writes one JSON object and one newline to stdout. Success and runtime errors use the same envelope.
{"schema_version":1,"ok":true,"data":{"inventory":"ready","devices":[]}}{"schema_version":1,"ok":false,"error":{"code":"inventory_not_ready","message":"agent inventory is not ready; no device operation was attempted"}}| Exit code | Meaning |
|---|---|
0 | Success. ok is true. |
1 | Runtime failure. Inspect error.code. |
2 | Invalid arguments. Clap writes diagnostics to stderr. |
Scripts must check both schema_version and ok. Scripts must ignore unknown object fields and treat unknown error codes as failures. Parse error.code, not the explanatory error.message.
The stable error codes are agent_unavailable, handshake_failed, version_mismatch, timeout, disconnected, inventory_not_ready, device_not_found, device_offline, ambiguous_device, unsupported_feature, invalid_value, readback_mismatch, device_error, identity_unavailable, link_override, config_error, config_conflict, config_busy, config_save_failed, config_reload_failed, and config_reload_unknown.
--help and --version produce text rather than JSON. A stdout write failure cannot produce a JSON envelope.
Device IDs and privacy
API device IDs are opaque identifiers for the current connection route. Refresh an ID after reconnecting a device or updating OpenLogi. Do not construct or parse IDs, and do not use array positions or device names as addresses.
A missing route has a null ID. Duplicate IDs remain in devices, and an operation using one returns ambiguous_device. IDs can contain hardware identity information, so keep them local and redact them before sharing output.
The device response excludes pairing passkeys, application history, and model serials. A null battery or capability is not a zero charge or an unsupported feature.