Essential OpenLogi Development Commands: A Complete Guide

The key OpenLogi development commands include cargo run -p openlogi for the CLI, cargo run -p openlogi-desktop for the GUI, and devenv tasks run openlogi:check for the full test gate, with packaging handled via the xtask crate.

OpenLogi is a multi-crate Rust workspace maintained by AprilNEA that provides a CLI tool, GPUI-based desktop client, background agent, and supporting infrastructure. Whether you are contributing to the core logic or building release artifacts, these OpenLogi development commands drive every stage of the workflow.

Running the Core Applications

Launching the CLI

Execute the thin openlogi wrapper to interact with connected devices directly from the terminal. This command builds and runs the openlogi crate in release mode:

cargo run -p openlogi --release -- list

To install the binary permanently onto your $PATH for convenient command-line use, run:

cargo install --path crates/openlogi

Starting the Desktop GUI

The desktop application resides in the openlogi-desktop crate and utilizes the GPUI framework. Launch the development bundle with:

cargo run -p openlogi-desktop --release

For workflow automation inside the reproducible devenv environment—which handles macOS-specific packaging helpers automatically—use:

devenv tasks run openlogi:gui

Using the Mock Agent

Develop the GUI without physical hardware by running the scripted in-memory HID agent. This binary is defined in crates/openlogi-agent:

cargo run -p openlogi-agent --bin openlogi-agent-mock

Workflow Automation with devenv

The repository supports devenv for reproducible development environments, defined in docs/DEVELOPMENT.md. These high-level tasks abstract the underlying Cargo commands.

Local Quality Gates

Run the formatted-check, Clippy, tests, and rustdoc suite for your current host—the equivalent of the CI "host-OS gate":

devenv tasks run openlogi:check

Reproducing CI Locally

Execute every GitHub Actions job that can be reproduced on your machine, including Linux clippy, Windows clippy, MSRV builds, and cargo-deny audits:

devenv tasks run openlogi:ci

Alternatively, invoke the underlying automation directly via the xtask crate:

cargo xtask ci

Building and Packaging

Release artifacts are generated through the xtask crate, which orchestrates platform-specific packaging logic.

macOS DMG Creation

Package the application into a signed DMG for macOS distribution:

cargo run -p xtask -- macos package

Linux Package Generation

Produce .deb, .rpm, and .pkg.tar.zst archives using nfpm:

cargo run -p xtask -- linux package

Manual Pre-Push Gates

When running outside devenv, mirror the exact checks performed before pushing changes by executing these commands sequentially:

export RUSTFLAGS="-D warnings"

cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps \
  --document-private-items --exclude openlogi-ui --exclude openlogi-desktop \
  --exclude openlogi-overlay --exclude openlogi-agent

These commands reference the workspace structure defined in Cargo.toml and exclude UI-specific crates from documentation checks.

Summary

• Run CLI binaries with cargo run -p openlogi --release or install globally via cargo install --path crates/openlogi.
• Launch the GUI using either direct Cargo commands or devenv tasks run openlogi:gui for automated environment handling.
• Test without hardware by starting the mock agent: cargo run -p openlogi-agent --bin openlogi-agent-mock.
• Execute quality gates via devenv tasks run openlogi:check or reproduce full CI with devenv tasks run openlogi:ci.
• Build releases through the xtask crate for macOS DMGs and Linux packages.
• Reference documentation in docs/DEVELOPMENT.md for authoritative workflow details.

Frequently Asked Questions

How do I develop the OpenLogi GUI without physical hardware?

Run the mock agent binary from the openlogi-agent crate: cargo run -p openlogi-agent --bin openlogi-agent-mock. This provides a scripted in-memory HID agent that simulates device connections, allowing full GUI development and testing without physical hardware attached.

What is the difference between devenv tasks and cargo xtask?

devenv tasks (e.g., devenv tasks run openlogi:check) execute high-level workflows inside a reproducible Nix-based development environment defined in docs/DEVELOPMENT.md. cargo xtask (e.g., cargo xtask ci) invokes the automation scripts directly from the xtask crate without the Nix sandbox, useful when devenv is not available.

Where are the packaging scripts located?

The packaging logic resides in the xtask crate, documented in xtask/README.md. Entry points include cargo run -p xtask -- macos package for DMG creation and cargo run -p xtask -- linux package for Debian and RPM archives.

How do I run the full test suite before submitting a pull request?

Execute devenv tasks run openlogi:check to run the host-OS gate, or devenv tasks run openlogi:ci to reproduce all possible CI jobs locally. For manual execution, run the specific cargo fmt, cargo clippy, cargo test, and cargo doc commands listed in docs/DEVELOPMENT.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}