# OpenLogi Usage Examples: CLI Commands and Configuration Guide

> Explore OpenLogi usage examples with CLI commands and configuration. Discover device management, asset sync, and diagnostic tools in this comprehensive guide. Learn how to leverage OpenLogi effectively.

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

---

**The fastest way to find OpenLogi usage examples is through the `openlogi` CLI binary, which exposes device management, asset synchronization, and diagnostic commands implemented in the `openlogi-cli` crate.**

OpenLogi is a native, local-first replacement for Logitech Options+ that bundles a GUI client, background agent, and overlay into a single installation. The project’s most accessible examples live in the command-line interface defined in [`crates/openlogi-cli/src/lib.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-cli/src/lib.rs), where every GUI feature is mapped to a typed sub-command using the **Clap** argument parser. These CLI commands serve as thin wrappers around the agent’s IPC protocol (documented in [`crates/openlogi-ipc/AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-ipc/AGENTS.md)), providing concrete patterns for interacting with paired hardware.

## Locating the CLI Entry Point and Documentation

The `openlogi` binary is implemented in the **`openlogi-cli`** crate. The entry point and command registration logic reside in [`crates/openlogi-cli/src/lib.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-cli/src/lib.rs), where the application parses arguments and dispatches to sub-command handlers. When invoked without arguments, the binary defaults to the `list` sub-command, which enumerates paired devices.

For a human-readable overview of all available operations, consult **[`docs/USAGE.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/USAGE.md)** in the repository root. This file catalogs every sub-command with brief descriptions and serves as the primary reference for syntax discovery.

## Basic Device Enumeration Examples

Listing connected peripherals is the default operation and requires no arguments.

```bash

# Display all paired devices with slot, codename, kind, online status, and battery level

openlogi list

```

This command reads the current device inventory from the background agent and prints a formatted table to stdout.

## Asset Synchronization Examples

OpenLogi manages device render assets (such as product images) through the `assets` sub-command. By default, the tool queries an automatic mirror selection, but you can specify a custom source.

```bash

# Synchronize assets from the default automatic mirrors

openlogi assets sync

# Use a specific mirror URL instead of automatic selection

openlogi assets sync --base https://my.custom.mirror/assets

```

You can also override the base URL via the **`OPENLOGI_ASSETS`** environment variable instead of the `--base` flag.

## Diagnostic Command Examples

The `diag` sub-command group exposes low-level HID++ functionality for testing hardware capabilities. These commands operate on the currently active device and are useful for verifying driver support.

### Inspecting HID++ Features

Dump the complete feature set reported by the active device:

```bash
openlogi diag features

```

### Querying Reprogrammable Controls

Show capability flags and reprogrammable control mappings:

```bash
openlogi diag controls

```

### Testing DPI Settings

Perform a validation routine that reads the current DPI, writes a temporary value, reads it back, and restores the original setting:

```bash
openlogi diag dpi

```

### Managing SmartShift and RGB Lighting

Toggle temporary states for specialized hardware features:

```bash

# Toggle SmartShift and revert to the previous state

openlogi diag smartshift

# Set a solid color on a wired RGB keyboard (RRGGBB hex format)

openlogi diag lighting ff0000

```

## Configuration File Examples

OpenLogi reads its startup configuration from **`~/.config/openlogi/config.toml`**. The repository provides a fully-tested template at **[`docs/config.example.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/config.example.toml)** that demonstrates how to define per-device bindings, Actions Ring layouts, and advanced feature flags. Copy this file to the user config directory and edit the TOML tables to customize behavior without recompiling.

## Debugging with Environment Variables

To inspect the IPC traffic between the CLI and the background agent, enable verbose tracing:

```bash
OPENLOGI_LOG=debug openlogi list

```

Setting **`OPENLOGI_LOG`** to `debug` exposes internal state transitions and wire-format messages, which is useful when extending the CLI or troubleshooting device detection failures.

## Summary

- The **`openlogi-cli`** crate in [`crates/openlogi-cli/src/lib.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-cli/src/lib.rs) provides the definitive source for usage examples.
- Running `openlogi` without arguments executes the `list` command to show paired devices.
- Use `openlogi assets sync` to download device renders, with optional `--base` or `OPENLOGI_ASSETS` overrides.
- Diagnostic commands (`diag features`, `diag controls`, `diag dpi`, `diag smartshift`, `diag lighting`) expose low-level hardware controls.
- Reference [`docs/config.example.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/config.example.toml) for TOML configuration patterns and [`docs/USAGE.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/USAGE.md) for command syntax.

## Frequently Asked Questions

### Where is the OpenLogi CLI source code located?

The CLI implementation is located in the `crates/openlogi-cli/` directory, specifically in [`src/lib.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/src/lib.rs) for the entry point and command routing. This crate uses the Clap parser to define the argument structure found in [`docs/USAGE.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/USAGE.md).

### How do I view all available OpenLogi commands?

Run `openlogi --help` or consult the [`docs/USAGE.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/USAGE.md) file in the repository. This document lists every sub-command—`list`, `assets`, and the `diag` family—with concise descriptions of their parameters and expected output.

### Can I use OpenLogi without the GUI?

Yes. The CLI is a first-class interface that communicates directly with the background agent via the IPC protocol defined in [`crates/openlogi-ipc/AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-ipc/AGENTS.md). All device management, configuration, and diagnostic functions available in the GUI can be executed from the terminal using the `openlogi` binary.

### How do I customize device bindings in OpenLogi?

Copy [`docs/config.example.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/config.example.toml) to `~/.config/openlogi/config.toml` and modify the TOML tables for your specific device codenames. The example file demonstrates how to map buttons, configure the Actions Ring, and set per-application profiles that the agent loads on startup.