How the Omarchy CLI Command Router Works: File-System Driven Dispatch

The Omarchy CLI command router is a lightweight dispatcher that maps space-separated commands to executables in bin/omarchy-* using a two-phase resolution algorithm combining fast-path filename probing with lazy metadata-driven longest-prefix matching.

The Omarchy CLI command router (implemented in bin/omarchy within the omacom/omarchy repository) eliminates traditional configuration files by deriving routes directly from filesystem patterns and embedded metadata. Unlike frameworks requiring explicit route registration, this system automatically discovers commands by scanning for binaries prefixed with omarchy-, translating human-readable arguments into executable calls through hyphen-joined filename matching.

Route Registration and Discovery

Executable Discovery Pattern

Every file in the bin/ directory matching the omarchy-* glob automatically becomes a routable command. The stem following the omarchy- prefix determines the command's identity, while the router treats hyphens in the original filename as spaces for the filename route (e.g., omarchy-theme-set becomes omarchy theme set).

Canonical vs. Filename Routes

The router registers two distinct route types for each binary:

• Canonical route — Derived from metadata comments (# omarchy:group=…, # omarchy:name=…) placed within the first 80 comment lines of the binary. This allows semantic naming independent of filesystem constraints.

• Filename route — Generated by converting hyphens to spaces in the actual filename.

Both routes remain active simultaneously, meaning a command responds to its canonical name and its filesystem-derived equivalent.

Route Collision Handling

When multiple binaries claim identical routes, the router implements a first-registration-wins policy. The conflict is recorded internally for later auditing via omarchy commands --check, which reports overlapping route definitions to assist in debugging namespace collisions.

The Dispatch Algorithm

The router employs a high-performance two-phase resolution strategy to minimize overhead:

Phase 1: Fast-Path Filename Probe

The router joins supplied arguments with hyphens and probes for a matching executable. For example, invoking omarchy theme set foo triggers sequential checks for bin/omarchy-theme-set-foo followed by bin/omarchy-theme-set. This phase requires zero metadata parsing and serves as the hot path for common invocations.

Phase 2: Metadata Fallback Resolution

If the fast-path probe fails, the router lazily loads command metadata from all binaries, constructs a comprehensive route table, and applies a longest-prefix matching rule. The longest matching prefix is selected as the target route; remaining arguments pass through to the executed binary.

Guarded Execution and Error Handling

Argument Validation

Commands declaring required arguments via the args metadata field trigger automatic help display when invoked without parameters, preventing malformed executions.

Process Replacement and Exit Codes

Dispatch utilizes exec to replace the router process entirely with the target binary, ensuring exit codes propagate directly from the executed command. Unknown routes cause the router to terminate with exit code 127.

Special Flag Interception

The router intercepts --help and -h flags regardless of their position in leftover arguments, guaranteeing consistent help behavior. Adding --json to any command requests structured JSON output describing the command's interface.

Prefix Listing and Route Suggestions

When resolution fails entirely, the router attempts prefix listing (e.g., omarchy hw asus lists all commands beginning with "hw asus") or suggests similar known routes, providing discoverability for partial matches without requiring exact syntax.

Command Introspection

The router exposes several self-documenting interfaces for automation and discovery:

• omarchy commands — Lists every non-hidden command with its summary.
• omarchy commands --all — Includes hidden plumbing commands in the listing.
• omarchy commands --json — Exports the complete routing table including routes, binaries, groups, names, summaries, flags, arguments, examples, and aliases.
• omarchy <route> --help — Displays the resolved binary path and indicates when the filename route differs from the canonical route.

Practical Usage Examples

# Simple dispatch using filename route

omarchy theme set dark            # Executes bin/omarchy-theme-set with argument "dark"

# Canonical route via metadata (binary: omarchy-install-gaming-xbox-cloud)

omarchy install gaming xbox-cloud   # Canonical route

omarchy install gaming xbox cloud   # Filename route still works

# Help interception works anywhere in argument list

omarchy update aur --help           # Resolves 'update' and forwards '--help'

# Prefix listing for partial matches

omarchy hw asus                    # Lists all commands starting with "hw asus"

# JSON introspection for tooling

omarchy commands --json            # Prints full routing table as JSON

Key Implementation Files

• bin/omarchy — Core router script implementing the fast-path probe, lazy metadata loading, and exec dispatch.

• bin/omarchy-* — Individual command binaries where the filename determines the default route.

• docs/cli-router.md — Authoritative specification of the routing behavior and metadata format.

• agents/skills/command-metadata.md — Specification of metadata comment keys (# omarchy:group, # omarchy:name, etc.).

• bin/omarchy (GROUP_DESCRIPTIONS table) — Defines top-level group titles controlling which groups appear in the top-level help listing.

Summary

• The Omarchy CLI router in bin/omarchy dispatches commands by mapping space-separated arguments to bin/omarchy-* executables using a fast-path filename probe followed by lazy metadata resolution.
• Route registration occurs automatically via filesystem scanning, supporting both metadata-defined canonical routes and hyphen-to-space filename routes derived from executable names.
• Collision handling uses first-registration-wins, with conflicts reported by omarchy commands --check.
• Guarded execution validates required arguments, uses exec for process replacement, and returns exit code 127 for unknown routes.
• Introspection tools provide JSON export (--json), prefix listing for partial matches, and help flag interception for enhanced discoverability.

Frequently Asked Questions

How does the Omarchy CLI router handle command name conflicts?

When two binaries claim the same route, the first registered route takes precedence and subsequent collisions are recorded internally. Run omarchy commands --check to audit these conflicts and identify which binaries overlap in their route definitions.

What happens if I type a partial command name?

The router attempts prefix matching when exact resolution fails. For example, entering omarchy hw asus lists all commands whose routes start with "hw asus", providing a discoverability mechanism for long command names without requiring full typing.

Can I use the original hyphenated filename instead of the space-separated command?

Yes. Both styles work simultaneously because the router registers the filename route (hyphens as spaces) alongside any canonical route defined in metadata. A binary named omarchy-install-gaming-xbox-cloud responds to both omarchy install gaming xbox-cloud and omarchy install gaming xbox cloud.

Where does the Omarchy CLI store its routing configuration?

The router requires no external configuration files. All routing information derives from two sources: the filesystem names of executables in bin/omarchy-* and metadata comments within the first 80 lines of those binaries (specifically # omarchy:group=… and # omarchy:name=… directives).

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