What Is the Main CLI Router for Omarchy Commands? Understanding bin/omarchy

The main CLI router for Omarchy commands is the bin/omarchy script, which parses user input and dispatches execution to specialized sub-command scripts under the bin/ directory.

The Omarchy open-source project implements a clean, modular command-line interface through a single entry-point router. Rather than a monolithic binary, Omarchy uses a dispatch pattern where bin/omarchy handles argument parsing and delegates actual work to purpose-built executable scripts. This architecture keeps the core router simple while enabling extensible, group-based command organization.

How bin/omarchy Routes Commands

The router script operates through a predictable parsing sequence. When you run omarchy <group> [action] [args], the script performs several key operations in order.

Argument Parsing and Group Lookup

bin/omarchy treats the first positional argument as a command group. It validates this group against an internal GROUP_DESCRIPTIONS associative array defined within the same file. This array maps group names to human-readable descriptions for help output.

# Group descriptions are defined directly in bin/omarchy

# Example groups: theme, toggle, update

Sub-Command Discovery and Execution

After identifying the group, the router searches for an executable matching the pattern omarchy-<group>-<action> in the bin/ directory. If found, it validates executability and delegates control. The script also handles hidden groups — those marked with omarchy:hidden=true — which remain functional but are excluded from help summaries.

Environment Setup

Before handing off to sub-commands, bin/omarchy establishes critical environment variables including $OMARCHY_PATH. This ensures all downstream scripts operate within a consistent runtime context.

CLI Router Usage Examples

Understanding the routing pattern helps predict which underlying script executes for any given command.

# Display top-level help showing all visible groups

omarchy help

# Route to theme group scripts (bin/omarchy-theme-*)

omarchy theme set dark

# Route to toggle group scripts (bin/omarchy-toggle-*)

omarchy toggle screensaver

# Hidden groups work when explicitly invoked

omarchy hidden-group some-action

Each invocation flows through bin/omarchy before reaching the actual implementation at bin/omarchy-<group>-<action>.

Core Files in the Routing Architecture

The Omarchy CLI system spans several coordinated files across the repository:

• bin/omarchy — The central router; handles parsing, group validation, hidden group filtering, environment setup, and sub-command dispatch.
• bin/omarchy-<group>-<action> — Individual command implementations (e.g., bin/omarchy-theme-set, bin/omarchy-toggle-screensaver).
• docs/testing.md — Documents how CLI routing behavior is validated through automated tests.
• AGENTS.md — Lists task-specific agents; explicitly includes the CLI router as a core system agent.

Summary

• bin/omarchy serves as the sole entry point and router for all Omarchy CLI commands.
• The script parses arguments into groups and actions, then dispatches to matching executables under bin/.
• Hidden groups remain functional but are excluded from help output via omarchy:hidden=true markers.
• Environment variables like $OMARCHY_PATH are initialized before sub-command execution.
• The modular design enables clean extension by adding new bin/omarchy-<group>-<action> scripts.

Frequently Asked Questions

How does Omarchy handle unknown or misspelled commands?

The bin/omarchy router validates groups against its internal GROUP_DESCRIPTIONS array. Unrecognized groups trigger appropriate error handling rather than silent failure, directing users toward valid commands via the help system.

Can I add custom command groups to Omarchy?

Yes. Create a new executable following the bin/omarchy-<group>-<action> naming convention and optionally add the group to GROUP_DESCRIPTIONS in bin/omarchy for visibility in help output. The router automatically discovers any executable matching its dispatch pattern.

What distinguishes visible from hidden groups in Omarchy?

Visible groups appear in standard help output and are listed in GROUP_DESCRIPTIONS. Hidden groups carry the omarchy:hidden=true marker and remain operational but unadvertised — useful for internal tooling, experimental features, or power-user functionality.

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