# How the Omarchy CLI Dispatch Mechanism Routes Commands: Fast Path vs. Metadata Resolution > Discover how the Omarchy CLI routes commands using its two-stage dispatch mechanism. Learn about fast path binaries and metadata resolution for efficient command handling. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: internals - Published: 2026-08-21 --- **The Omarchy CLI dispatch mechanism employs a two-stage router that first probes for direct binary matches via filesystem checks, then lazily loads command metadata to resolve aliases, renamed routes, and help requests.** The Omarchy command-line interface from the `basecamp/omarchy` repository implements a lightweight yet sophisticated dispatch system that balances execution speed with routing flexibility. Unlike traditional CLI frameworks that rely solely on argument parsing, Omarchy's **Omarchy CLI dispatch mechanism** maps spaced command invocations (`omarchy `) directly to flat executable files while maintaining support for dynamic routing through embedded metadata comments. ## Route Derivation: Mapping Files to Command Namespaces At initialization, the router scans the `bin/` directory and derives command routes from filenames and embedded metadata. The stem after the `omarchy-` prefix is split at the first hyphen to obtain a **group** and **name** (e.g., `omarchy-theme-set` yields group `theme` and name `set`). If no hyphen exists, the entire stem becomes a root command within its own group. According to the source in `bin/omarchy`, specifically within the `register_command` function at lines 51-66, the system registers two routes for each binary: - The **canonical** route derived from metadata comments (e.g., `# omarchy:name=gaming xbox-cloud`) - The **filename** route where hyphens become spaces Both routes remain valid even when metadata changes, ensuring backward compatibility. The function constructs `fallback_group`, `fallback_name`, and `fallback_route` variables to handle these dual registrations. ## Fast-Path Dispatch: The Hot Path Optimization When a user invokes a command, the router prioritizes speed through a filesystem probe before parsing any metadata. In `resolve_direct_route` (lines 95-100) and `dispatch_fast_or_help` (lines 46-73), the mechanism joins supplied arguments with hyphens to construct a candidate filename (e.g., `omarchy-theme-set`) and checks for executable existence. If a match exists, the binary executes immediately without loading command metadata. This **fast path** reduces latency dramatically for standard invocations, bypassing the overhead of parsing comment headers or building route tables. ## Metadata-Driven Resolution and Fallbacks When the fast path finds no direct binary match—such as when using a metadata-defined alias or a renamed command—the router falls back to metadata-driven resolution. The functions `resolve_route` and `dispatch_or_help` (lines 16-28 and 10-17) perform this secondary stage by: 1. Loading metadata from all `bin/omarchy-*` files (lazy loading) 2. Building a comprehensive route table 3. Resolving the longest-prefix route that maps to a registered command This approach allows commands to move or acquire aliases without breaking existing user scripts, as the metadata layer abstracts the physical filename from the invocation route. ## Help-First Behavior and Argument Guarding The dispatch mechanism prioritizes user assistance over execution during ambiguous states. When the fast path detects a binary match but the argument list contains `--help` or `-h`, the router loads the command's metadata lazily and displays help text rather than executing the binary. The same logic applies to `--help` requests (lines 56-71). Additionally, **argument guarding** prevents accidental launches of commands requiring explicit parameters. If a binary declares required arguments via the `# omarchy:args=` comment header and the user supplies none, the router displays usage information instead of executing the command (lines 35-42). ```bash # Fast-path execution $ omarchy theme set solarized # Executes bin/omarchy-theme-set directly # Help request triggers metadata loading $ omarchy theme set --help # Loads metadata and prints help instead of executing # Metadata-defined route resolution # File: bin/omarchy-install-gaming-xbox-cloud # Header: # omarchy:name=gaming xbox-cloud $ omarchy install gaming xbox-cloud # Resolved via metadata table, not direct file probe ``` ## Group Listings and Route Collision Handling When users invoke a group without specifying a subcommand (e.g., `omarchy theme`), the router detects available child commands and displays a group help listing via `show_group_help` (lines 93-106). For unrecognized commands, `suggest_command` and `show_prefix_help` (lines 31-44) provide "did you mean" suggestions based on prefix matching. The system also detects route collisions. If two different binaries register identical routes, the first registration wins while subsequent clashes are recorded in the `ROUTE_COLLISIONS` array. These conflicts surface when running `omarchy commands --check`, enabling repository linting. ```bash # Group help display $ omarchy theme # Lists all available theme subcommands # Argument guard prevents empty invocations $ omarchy theme set # Shows help because set requires an argument (--help behavior) ``` ## Summary - The **Omarchy CLI dispatch mechanism** implements a two-stage router combining filesystem probes with metadata resolution. - **Fast-path dispatch** joins arguments with hyphens to check for executable existence at `bin/omarchy-`, executing immediately if found. - **Metadata-driven resolution** loads command headers lazily to handle aliases, renamed routes, and help generation when the fast path misses. - **Argument guarding** uses `# omarchy:args=` comments to prevent execution of parameter-dependent commands without inputs. - **Route collisions** are tracked in `ROUTE_COLLISIONS` and reported via `omarchy commands --check` for quality assurance. ## Frequently Asked Questions ### What happens if two Omarchy commands define the same route? The first binary to register the route wins, and subsequent registrations are recorded in the `ROUTE_COLLISIONS` array. These conflicts remain latent during normal operation but are flagged when running `omarchy commands --check`, allowing maintainers to identify and resolve overlapping command definitions. ### How does Omarchy handle command aliases defined in metadata? Aliases specified via `# omarchy:alias=` comments are resolved during the metadata-driven fallback stage. When the fast path fails to find a direct binary match for the alias, the router loads all command metadata and maps the alias to its canonical binary, enabling short command forms without requiring separate executable files. ### Why does Omarchy use a two-stage dispatch instead of parsing all metadata upfront? Parsing all metadata on every invocation would introduce significant latency. By checking for direct file matches first through `resolve_direct_route`, the router avoids overhead for the common case where command filenames match invocation patterns. Metadata parsing occurs only when necessary for help requests, aliases, or renamed commands, optimizing for execution speed. ### What occurs when I run `omarchy theme` without specifying a subcommand? The router recognizes `theme` as a valid group with child binaries and invokes `show_group_help` to display a formatted listing of all available theme subcommands. This behavior provides discoverability without requiring a separate help flag, falling back to prefix suggestions only if no matching group or command exists.