# How the Omarchy CLI Router Resolves Subcommands: Inside bin/omarchy > Learn how the omarchy CLI router resolves subcommands via discovery registration longest prefix matching and fallback resolution Understand the inner workings of bin omarchy - Repository: [Omacom/omarchy](https://github.com/omacom/omarchy) - Tags: internals - Published: 2026-09-04 --- **The Omarchy CLI router resolves subcommands through a three-phase process: discovery and registration of command metadata, longest-prefix binary matching, and fallback resolution with preserved argument forwarding.** The `omacom/omarchy` repository implements a sophisticated command-line interface driven by a single router script located at `bin/omarchy`. When users execute `omarchy` followed by arguments, the router transforms textual input into executable subcommands through deterministic prefix matching and route table lookups. Understanding how the **omarchy CLI router resolves subcommands** reveals a design that supports deep command hierarchies while maintaining simplicity and flag preservation. ## Command Discovery and Registration The router begins by mapping the entire command space available in the `bin/` directory. This discovery phase builds the internal route tables that power subsequent resolution. ### Scanning for Executables with load_commands At startup, the `load_commands` function scans every executable file whose name begins with `omarchy-` in the same directory. The router treats each file as a potential command endpoint, regardless of whether it represents a top-level command or a nested subcommand. This filesystem-based discovery allows the CLI to remain extensible—adding new commands requires only dropping new executables into `bin/` with the proper naming convention. ### Parsing Metadata Comments in register_command Each command file can embed configuration through special comment lines that the router parses during registration. As implemented in `omacom/omarchy`, the `register_command` function processes these metadata tags beginning around lines 200–210 of `bin/omarchy`. Common metadata patterns include: ```bash # omarchy:group=update # omarchy:name=install ``` From this metadata—or derived directly from the filename—the router constructs route strings such as `omarchy update` or `omarchy update aur`. These routes populate three key data structures: - `COMMAND_ROUTE` – Associates textual routes with their implementing binaries - `COMMAND_FALLBACK_ROUTE` – Stores secondary routing options for ambiguous prefixes - `COMMAND_ALIASES` – Maps shortcut names to full command paths ## Longest-Prefix Direct Resolution Once the route tables are populated, the router enters the resolution phase when the user provides arguments. This phase prioritizes exact binary matching over route table lookups. ### The resolve_direct_route Algorithm Starting at line 398 of `bin/omarchy`, the `resolve_direct_route` function implements a greedy longest-prefix matching algorithm. The function iterates over the argument list from longest to shortest prefix, building candidate binary names by joining arguments with hyphens. The resolution process follows this pattern: 1. Build candidate name: `omarchy-$(join_words "-" "$@")` 2. Check if file exists and is executable 3. On first match, record resolution metadata and stop The router stores resolution details in three variables: - `DIRECT_RESOLVED_BINARY` – The absolute path to the executable that will be invoked - `DIRECT_RESOLVED_COUNT` – The number of argument tokens consumed by the match - `DIRECT_RESOLVED_ROUTE` – The textual route string that matched ### Argument Consumption and Binary Mapping When executing `omarchy theme set dracula`, the router tests prefixes in descending order of length: ```bash # Candidate 1: omarchy-theme-set-dracula (does not exist) # Candidate 2: omarchy-theme-set (exists at bin/omarchy-theme-set) -> MATCH ``` The router consumes `theme` and `set` as the route prefix, leaving `dracula` as remaining arguments. This design enables arbitrarily deep subcommand hierarchies—such as `omarchy config get editor`—while keeping the routing logic linear and predictable. ## Fallback Resolution and Execution When direct binary resolution fails, the router falls back to the route tables built during the discovery phase. ### Route Table Lookups If no executable matches the longest argument prefix, the router consults `COMMAND_ROUTE`, `COMMAND_FALLBACK_ROUTE`, and `COMMAND_ALIASES` to locate the intended command definition. Hidden commands—those marked with appropriate metadata—are omitted from help listings unless the user explicitly requests `--all`. ### Preserving Flags and Arguments The router guarantees that flags intended for the final command are never swallowed during resolution. Around lines 28–35, the helper function `remaining_has_help_flag` checks for `--help`, `--json`, or `--` separators in the remaining arguments. The router then executes the resolved binary, passing **all** remaining arguments unchanged: ```bash # Example: Flags preserved through routing $ omarchy update --json aur ``` In this case, `resolve_direct_route` identifies `bin/omarchy-update` as the target binary. The router invokes it with `--json aur` intact, allowing the command to handle JSON output formatting or interpret `aur` as a package source. ```bash # Complete routing example with separator $ omarchy config set -- editor --wait ``` Here, the router resolves to `bin/omarchy-config-set`, but preserves both the `--` separator and the subsequent flags for the command implementation to process. ## Summary - The **omarchy CLI router** operates from a single entry point at `bin/omarchy` that orchestrates subcommand discovery and dispatch. - **Discovery phase** (`load_commands`, `register_command`): Scans `bin/omarchy-*` executables and parses metadata comments (lines 200–210) to populate route tables including `COMMAND_ROUTE` and `COMMAND_ALIASES`. - **Resolution phase** (`resolve_direct_route`): Implements longest-prefix matching (lines 398–405) to map arguments to binaries like `omarchy-theme-set`, storing results in `DIRECT_RESOLVED_BINARY` and related variables. - **Execution phase**: Falls back to route tables when direct binary resolution fails, preserving all flags, `--help`, `--json`, and `--` separators for the target command (lines 28–35). - The prefix-tree architecture supports deep hierarchies (`omarchy theme set dark`) while remaining deterministic and extensible through filesystem-based command discovery. ## Frequently Asked Questions ### How does the Omarchy router handle ambiguous command prefixes? The router resolves ambiguity through **longest-prefix matching** in `resolve_direct_route`. It tests candidate binaries by consuming arguments from left to right until finding an existing executable. If no direct binary matches, it falls back to the `COMMAND_ROUTE` and `COMMAND_FALLBACK_ROUTE` associative arrays to find the intended command. This ensures that `omarchy update` takes precedence over a hypothetical shorter match. ### Can command files exist outside the bin/ directory? According to the `omacom/omarchy` source code, the router restricts discovery to executables within the same directory as the router script (`bin/`). The `load_commands` function specifically scans for files beginning with `omarchy-` in this directory. Commands must be installed into `bin/` to be recognized, maintaining a centralized, predictable command structure. ### What happens to flags like --help when routing commands? The router preserves all flags and arguments for the final command implementation. The helper `remaining_has_help_flag` (lines 28–35) specifically checks for help flags, but the router never consumes them. When `resolve_direct_route` identifies the target binary, it executes the command with all remaining arguments—including `--help`, `--json`, or `--` separators—passed through unchanged. This prevents the router from intercepting flags meant for subcommands. ### How are command groups and aliases defined? Groups and aliases are defined through **metadata comments** within command files. The `register_command` function parses lines like `# omarchy:group=update` to categorize commands and build route strings. Aliases populate the `COMMAND_ALIASES` array, allowing multiple invocation paths to target the same binary. Both explicit metadata and filename conventions (`omarchy-group-subcommand`) contribute to the final route mapping.