# Best Practices for Using the Omarchy CLI: A Complete Developer Guide

> Master the Omarchy CLI with this developer guide. Learn best practices for routing commands, validation, and JSON output for robust scripting and automation.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: best-practices
- Published: 2026-09-12

---

**The Omarchy CLI routes human-readable spaced commands to flat binaries using longest-prefix resolution, and following canonical routes, metadata-driven validation, and JSON output ensures robust scripting and future-proof automation.**

The Omarchy CLI in the `omacom/omarchy` repository provides a thin routing layer that maps intuitive, space-separated commands to executable binaries. Understanding the router's architecture, metadata parsing rules, and IPC integration is essential for writing reliable scripts and maximizing interactive efficiency when managing your Omarchy environment.

## Understanding the CLI Router Architecture

The CLI router, located at `bin/omarchy`, serves as the central dispatch mechanism for all commands. It performs a fast-path filename probe to locate binaries matching the `omarchy-*` pattern, then implements **longest-prefix resolution** to determine the correct executable. When metadata is required, the router lazily loads optional header comments from command files, reading only the first 80 lines to maintain performance.

Command binaries reside in the `bin/` directory following the naming convention `bin/omarchy-<group>-<name>`. For example, `bin/omarchy-theme-set` registers as the `theme set` command. The router uses a hand-curated `GROUP_DESCRIPTIONS` table within `bin/omarchy` to generate help text, while **hidden commands** remain routable but excluded from listings.

### Metadata-Driven Command Discovery

Metadata comments use the format `# omarchy:key value` and support fields including `summary`, `group`, `name`, `args`, `examples`, and `hidden`. The router consumes this metadata to generate usage information and validate arguments. If a command requires arguments but receives none, the router automatically displays usage text instead of executing the binary, protecting scripts from incomplete invocations.

## Using Canonical Routes for Stability

Always invoke commands through the **canonical group/name form** rather than direct binary execution. Use `omarchy theme set dark` instead of `omarchy-theme-set dark`. The canonical route respects metadata overrides, handles argument validation, and remains stable even if underlying binaries are renamed or reorganized during updates.

Directly invoking `bin/omarchy-*` binaries bypasses the router's metadata processing and argument validation. This approach breaks when commands are renamed or when new validation logic is added to the metadata layer, making scripts fragile across version upgrades.

## Introspection and Debugging Strategies

The `omarchy commands` subcommand provides comprehensive registry inspection for troubleshooting and CI integration. Use `omarchy commands --all` to reveal hidden commands, `--json` for machine-readable output, and `--markdown` for documentation generation.

Run `omarchy commands --check` in CI pipelines to detect missing summary fields, route collisions, or non-executable binaries before deployment. For detailed routing logic, examine [`docs/cli-router.md`](https://github.com/omacom/omarchy/blob/main/docs/cli-router.md), which documents the dispatch algorithm, fast-path probing, and the 80-line metadata reading limit.

## Automation and Scripting Best Practices

When building automation around the Omarchy CLI, specify `--json` for commands like `omarchy version` and `omarchy commands` to parse structured data reliably. This eliminates fragility from parsing human-readable text that may change between versions.

Handle argument requirements gracefully by allowing the router to display usage when arguments are omitted. For quiet execution that fails silently when the Quickshell instance is unavailable, append the `-q` flag to commands that interact with the UI.

### Practical Code Examples

```bash

# List all public commands with summaries in Markdown format

omarchy commands --markdown

# Export full command registry as JSON for tooling integration

omarchy commands --all --json > cmd-registry.json

# Validate CLI integrity in CI pipelines

omarchy commands --check

# Execute via canonical route with automatic usage display when args missing

omarchy toggle input-device

# Apply theme quietly (best-effort if shell unavailable)

omarchy theme set dracula -q

```

## Shell IPC and UI Integration

UI-affecting commands ultimately communicate with the running Quickshell instance via `omarchy-shell` IPC, as documented in [`docs/omarchy-shell.md`](https://github.com/omacom/omarchy/blob/main/docs/omarchy-shell.md). If the shell process is not running, most commands fail fast unless executed with `-q`. Structure scripts to check for shell availability or use quiet mode when executing best-effort side effects.

Group-scoped help improves discoverability in both interactive and scripted contexts. Execute `omarchy <group> --help` to list only commands within a specific group, reducing output noise when programmatically searching for functionality. For example, `omarchy theme --help` shows only theme-related commands without cluttering output with unrelated groups.

## Summary

- **Use canonical routes** (`omarchy group name`) instead of direct binary calls to ensure metadata validation and future compatibility.
- **Leverage `--json` and `--markdown` flags** for stable automation output that resists formatting changes.
- **Run `omarchy commands --check`** in CI to catch metadata errors, missing summaries, and routing collisions.
- **Include the `-q` flag** for UI commands that should fail silently when the Quickshell IPC layer is unavailable.
- **Respect the 80-line limit** for metadata comments in command binaries to ensure the router parses your command definitions correctly.
- **Target group-specific help** (`omarchy <group> --help`) to streamline command discovery and reduce parsing overhead in scripts.

## Frequently Asked Questions

### What is the difference between canonical routes and direct binary calls in Omarchy?

**Canonical routes** (e.g., `omarchy theme set`) route through `bin/omarchy` and respect metadata validation, argument checking, and future renames. Direct binary calls (e.g., `omarchy-theme-set`) bypass the router entirely, skipping validation and breaking when metadata changes or binaries move to new locations.

### How does the Omarchy CLI handle missing arguments?

The router detects missing required arguments through metadata and automatically displays usage information instead of executing the command. This protects scripts from running with incomplete parameters, as seen when running `omarchy toggle input-device` without specifying the device name.

### Can I use the Omarchy CLI without Quickshell running?

Most UI-affecting commands fail fast if the `omarchy-shell` IPC connection is unavailable. Use the `-q` flag to execute commands quietly in best-effort mode, which prevents error output when the shell is absent while still attempting the requested side effect.

### How do I programmatically list all available Omarchy commands?

Use `omarchy commands --all --json` to output the complete command registry in structured format, or `omarchy commands --markdown` for documentation-friendly output. The `--check` flag validates registry integrity, catching issues like missing summaries or route collisions in CI pipelines.