# How the Omarchy CLI Router Resolves Commands: A Technical Deep Dive > Explore how the Omarchy CLI router resolves commands using longest-prefix matching, metadata extraction, and exec dispatch for efficient command execution. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: deep-dive - Published: 2026-08-29 --- **The Omarchy CLI router resolves commands by performing longest-prefix matching against binaries in `bin/`, extracting metadata from leading comments, and dispatching matched executables via `exec` while falling back to help text or prefix listings when no exact match exists.** The `basecamp/omarchy` repository implements a lightweight yet sophisticated command-line interface through its central router script located at `bin/omarchy`. This router serves as the primary dispatcher for the `omarchy` command, transforming user arguments into executable instructions through a deterministic resolution algorithm. Understanding this routing mechanism is essential for extending Omarchy with custom commands or integrating its CLI into automation workflows. ## Longest-Prefix Matching Algorithm At the core of Omarchy's command resolution lies a **longest-prefix matching** strategy that prioritizes specific matches over general ones. When a user invokes `omarchy` with arguments, the router attempts to match the complete argument list against available routes before progressively shortening the prefix. ### Progressive Argument Evaluation According to the implementation documented in [`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md) (lines 49-52), the router first attempts to match the **full argument list** against the filesystem. If no binary exists for that specific path, the router removes the last argument and retries with the shortened prefix. This process continues until either a match is found or the argument list is exhausted, ensuring that complex subcommands like `omarchy theme set` resolve correctly before falling back to simpler `omarchy theme` commands. ### Metadata Extraction from Binaries Each executable binary in the `bin/` directory may contain a leading comment line that provides descriptive metadata. As specified in [`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md) (lines 43-44), the router extracts comments formatted as `# omarchy:summary=` to generate help text and provide command summaries. This convention allows the router to build dynamic help menus without requiring a separate configuration file. ## Alias Resolution Strategy The Omarchy CLI router handles command aliases through a two-tier lookup mechanism that balances direct execution with flexible naming conventions. ### Direct Binary Matching When resolving a command such as `omarchy screenshot`, the router first searches for a binary named exactly `omarchy-screenshot` in the `bin/` directory. If this direct match exists, the router immediately prepares it for execution without additional processing. ### Alias Table Fallback If no direct binary match exists, the router consults its internal alias mapping. As detailed in [`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md) (lines 63-66), aliases like `screenshot` map to specific command groups (e.g., `omarchy-capture-screenshot`). The router loads the entire route set and resolves the alias to the appropriate executable, enabling shorter command names without duplicating binaries. ## Command Dispatch and Execution Once the router identifies a concrete route, it employs a direct execution model that replaces the routing process entirely. ### The Exec Dispatch Mechanism The router uses the `exec` builtin to transform the current process into the target binary. As implemented in [`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md) (lines 82-84), the router constructs the command: ```bash exec "$binary" "${remaining_args[@]}" ``` This approach ensures that the target binary receives only the arguments following its resolved name, and the exit code returned to the shell originates directly from the executed command rather than the router itself. ### Help Fallback Behavior When invoked without arguments, the router displays a global help overview instead of attempting execution. This behavior, documented at lines 78-80 of [`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md), lists available commands using their extracted metadata summaries, providing immediate orientation for new users. ### Prefix Listing Mode If the router cannot resolve the provided arguments to any known route, it enters a **prefix-listing** mode. According to [`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md) (lines 86-88), the system displays valid subcommands that share the given prefix. For example, invoking `omarchy hw` might list `omarchy hw asus` and `omarchy hw intel` as available continuations, guiding users toward valid syntax interactively. ## Machine-Readable Route Discovery For integration with external tooling and automation scripts, the Omarchy CLI router supports structured output formats. ### JSON Route Export Adding the `--json` flag to the base `omarchy` command causes the router to emit a complete JSON description of every available route. As specified in [`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md) (lines 130-132), this output includes command paths, metadata summaries, and binary locations, enabling programmatic discovery without parsing human-readable help text. ## Practical Examples The following examples demonstrate the Omarchy CLI router's resolution behavior in practice: ```bash # Longest-prefix matching executes `omarchy-theme-set` with "dark" as argument omarchy theme set dark # Alias resolution maps `screenshot` to `omarchy-capture-screenshot` omarchy screenshot # No arguments triggers help fallback omarchy # Unknown prefix triggers listing of valid `hw` subcommands omarchy hw unknown # Machine-readable route dump for tooling omarchy --json ``` ## Summary - The Omarchy CLI router in `bin/omarchy` implements **longest-prefix matching** to resolve complex subcommands before falling back to simpler prefixes. - Command metadata derives from `# omarchy:summary=` comments within binary files, eliminating the need for external configuration. - **Alias resolution** first attempts direct binary matching, then consults an internal mapping table for flexible command naming. - The router uses **`exec`** to replace itself with the target binary, ensuring accurate argument passing and exit code propagation. - **Fallback mechanisms** include global help display (no arguments) and prefix listing (unknown commands) to guide user interaction. - The **`--json`** flag enables machine-readable route discovery for automation and integration tasks. ## Frequently Asked Questions ### How does the Omarchy CLI router handle unknown commands? When the router encounters arguments that match no known route, it activates prefix-listing mode. As documented in [`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md) (lines 86-88), the system displays valid subcommands that share the provided prefix, helping users identify correct syntax. For example, `omarchy hw unknown` would list available hardware-specific commands like `omarchy hw asus` or `omarchy hw intel`. ### What is the difference between a direct binary and an alias in Omarchy? Direct binaries exist as files named `omarchy-` in the `bin/` directory and execute immediately upon matching. Aliases, conversely, provide shorter names that map to longer binary names through the router's internal resolution table. According to [`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md) (lines 63-66), the router checks for direct matches first, then falls back to alias resolution only when no direct binary exists. ### How can I list all available Omarchy commands programmatically? Invoke `omarchy --json` to receive a structured JSON array containing every available route, its summary description, and binary location. This output, described in [`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md) (lines 130-132), provides machine-readable metadata suitable for building autocompletion scripts or integration dashboards without parsing shell output. ### Where is the Omarchy CLI router source code located? The primary routing logic resides in `bin/omarchy`, while the design specification and resolution algorithm details are documented in [`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md). Individual commands follow the naming convention `bin/omarchy-` and may include metadata comments that the router extracts for help generation.