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

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, 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

# 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. 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.

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