Command line

Use openlogi for device information, diagnostics, and local automation. This guide covers v0.8.11; the --save option described below requires a newer development build.

Find the command

Linux packages and the Windows MSI install openlogi on your PATH. Open a new terminal after installing the MSI. For a macOS app or Windows portable archive, use the bundled executable:

# macOS, with OpenLogi installed in /Applications
/Applications/OpenLogi.app/Contents/MacOS/openlogi --version

# Windows portable archive, from the extracted app directory
.\bin\openlogi.exe --version

Use the applicable executable path wherever the examples below say openlogi. See Installation for packages and source builds.

Everyday commands

openlogi list
openlogi assets sync
openlogi --help

list shows connected receivers, paired devices, and Logitech webcams. It uses a compatible running agent when available and otherwise enumerates hardware directly. Running openlogi without a subcommand also runs list. An empty scan exits with status 2.

assets sync downloads device renders. OPENLOGI_LOG=debug enables verbose tracing; logs go to stderr.

JSON automation

Start OpenLogi before running openlogi api. These commands require a running agent with a compatible protocol. They do not start the agent or access hardware directly. Use matching CLI and agent builds if you receive version_mismatch.

openlogi api status
openlogi api devices

status reports agent health and permissions. devices returns device IDs, connection state, battery information, and measured capabilities. Device operations require inventory: "ready"; an empty array means no peripherals only when inventory is ready. scanning and unavailable are distinct states. Cameras are outside this API.

Copy an exact, non-null id from api devices. Replace DEVICE_ID in the following examples with that value and keep the quotes. Use the mouse's ID for DPI and SmartShift, and a compatible keyboard's ID for Fn lock.

openlogi api dpi --device "DEVICE_ID"
openlogi api smartshift --device "DEVICE_ID"
openlogi api fn-lock --device "DEVICE_ID"

IDs identify the current connection route. Refresh them after reconnects or updates; do not build IDs from a device name or use them as configuration keys. An ID that matches multiple devices returns ambiguous_device. IDs may contain hardware identity information, so redact them before sharing output. A null battery or capability value means no measured value is available.

Change a setting

The commands above only read. Add a setting flag to apply a change immediately:

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

• DPI: choose a value from the supported array returned by the read command. Unsupported values are rejected instead of rounded.
• SmartShift: omitted fields retain their current values. --mode ratchet alone does not change the automatic-release threshold; add --auto-disengage 255 for permanent ratchet. Thresholds 1–254 use firmware units of 0.25 turn/s; 0 is invalid.
• Fn lock: on makes bare function keys send F1–F12; off selects their printed media functions.

DPI and SmartShift writes are read back; Fn lock checks the firmware response. If a write times out, disconnects, or fails verification, read the setting again before deciding whether to retry. The hardware may already have changed.

JSON and exit status

After arguments parse, each API invocation writes one JSON object and a newline to stdout. For example, a successful device scan with no peripherals returns:

{"schema_version":1,"ok":true,"data":{"inventory":"ready","devices":[]}}

A runtime error uses the same envelope:

{"schema_version":1,"ok":false,"error":{"code":"inventory_not_ready","message":"agent inventory is not ready; no device operation was attempted"}}

Check both schema_version and ok in scripts. Ignore unknown object fields and treat unknown error codes as failures. Use error.code for decisions; error.message is explanatory text. --help and --version return text, and a stdout write failure cannot provide a JSON envelope.

Save settings in development builds

In those builds, add --save to an explicit DPI, SmartShift, or Fn-lock change:

openlogi api dpi --device "DEVICE_ID" --set 1200 --save

The command verifies the hardware result, saves that setting, and requests an agent configuration reload. Success returns persistence: "saved". Saving requires a discovered physical-device identity and refuses a conflicting per-connection override. SmartShift thresholds must be 8–255 when saving.

Hardware writes, file saves, and reloads are separate steps. A later failure does not undo the hardware change. On save or reload failure, inspect error.persistence: not_saved means the file was not saved; saved means the file was saved but reload failed or its outcome is unknown. Reload errors still exit with status 1. See the CLI reference for conflict handling and error codes.

Hardware diagnostics

Use openlogi diag --help to inspect diagnostic commands. diag features and diag controls report device capabilities. Other diagnostics can write hardware: by default, diag dpi and diag smartshift perform changes and restore them on successful completion, while diag lighting applies a color. Use the API above for routine scripts.

Reference: v0.8.11 CLI guide · Development CLI guide