# How the Omarchy CLI Router Dispatches Commands to bin/omarchy-* Binaries > Discover how the Omarchy CLI router dispatches commands to bin/omarchy-* binaries. Learn about dynamic binary discovery, longest-prefix matching, and process replacement for efficient command execution. - Repository: [Omacom/omarchy](https://github.com/omacom/omarchy) - Tags: internals - Published: 2026-09-09 --- **The Omarchy command-line interface uses a single router script at `bin/omarchy` that dynamically discovers helper binaries via filesystem scanning, resolves user input through longest-prefix matching, and delegates execution via process replacement.** The Omarchy project—hosted at `omacom/omarchy`—implements a file-based command routing system that treats the `bin/` directory as a self-documenting command registry. Unlike traditional CLI frameworks that rely on centralized switch statements, the Omarchy CLI router dynamically maps user arguments to executable binaries using naming conventions and prefix matching. This architecture enables zero-configuration extensibility: adding a new command requires only dropping a properly named executable into the `bin/` folder. ## Command Discovery in the bin/ Directory The routing process begins when the main script scans the directory referenced by `"$OMARCHY_PATH/bin"` (or the bundled `bin/` directory within the repository). The router identifies every executable file whose name starts with the `omarchy-` prefix and treats each as a discrete route. The filename itself defines the command path, with hyphens representing sub-command boundaries. For example: - `bin/omarchy-theme-set` registers the route `theme set` - `bin/omarchy-toggle-touchpad` registers the route `toggle touchpad` - `bin/omarchy-weather-location` registers the route `weather location` This filesystem-based discovery mechanism means the router automatically recognizes new commands without requiring updates to internal lookup tables or configuration files. ## Longest-Prefix Route Resolution When a user invokes the CLI, the router applies a longest-prefix matching algorithm to resolve the target binary. According to the implementation in `bin/omarchy`, the router walks the user-supplied arguments from left to right, attempting to match the longest possible sequence against the discovered routes. Consider the command `omarchy theme set dark`: 1. The router first tests the full argument list `theme set dark` against all available routes. 2. Finding no exact match for three tokens, it shortens the candidate to `theme set`. 3. This sequence matches the `omarchy-theme-set` binary, establishing it as the command target. 4. The remaining argument (`dark`) is preserved to pass to the binary. If the router exhausts all possible prefixes without finding a match, it falls back to alias resolution or prefix listing modes. ## Alias Handling and Prefix Fallbacks When exact route resolution fails, the router consults built-in alias tables defined within `bin/omarchy` itself. These aliases map common shorthand invocations to their full binary equivalents—for instance, routing `omarchy screenshot` to the `omarchy-capture-screenshot` binary. The router also implements intelligent fallbacks for incomplete input: - **Help generation**: Invoking `omarchy` without arguments triggers a help display aggregated from metadata embedded in each helper binary. - **Prefix listing**: Partial matches like `omarchy hw asus` scan for all binaries matching the pattern `omarchy-hw-asus-*`, presenting the user with available sub-commands rather than failing with an error. ## Process Replacement via Exec Dispatch Once the router identifies the correct binary, it does not spawn a child process. Instead, it replaces its own process image entirely using the `exec` system call. As documented in [`docs/cli-router.md`](https://github.com/omacom/omarchy/blob/main/docs/cli-router.md), this dispatch strategy provides two critical behaviors for shell integration. First, the executed binary receives only the *remaining* arguments—the tokens not consumed by the longest-prefix match. In the invocation `omarchy theme set dark`, the binary at `bin/omarchy-theme-set` receives only `dark` as its argument vector. Second, because the original router process is replaced rather than wrapped, the exit status of the helper binary propagates directly to the shell. This makes the router transparent to scripts that depend on accurate return codes for error handling or conditional execution flows. ## Embedded Metadata and Automatic Documentation Each helper binary can expose descriptive metadata through structured comments. The router parses lines beginning with `# omarchy:summary=` to extract short descriptions for each command during the discovery phase. When generating the global help output, `bin/omarchy` aggregates these summaries from all discovered `bin/omarchy-*` files. This allows the central help text to remain synchronized with the actual command implementations without requiring manual updates to a centralized documentation file. ## Summary - The router at `bin/omarchy` scans `"$OMARCHY_PATH/bin"` for executables prefixed with `omarchy-` to build the command registry dynamically. - Longest-prefix matching resolves user arguments to the most specific available binary, passing unmatched tokens as remaining arguments. - Built-in aliases and prefix listings provide graceful fallbacks when exact matches do not exist. - The `exec` system call replaces the router process, ensuring transparent exit code propagation and argument isolation. - Metadata comments (`# omarchy:summary=`) enable automatic help generation without centralized configuration. ## Frequently Asked Questions ### How does the Omarchy CLI discover available commands? The router dynamically builds its command manifest at runtime by scanning the `bin/` directory for files matching the `omarchy-*` naming pattern. Each executable found automatically registers a route corresponding to its filename, requiring no additional configuration or registration steps. ### What happens if I type a partial command that does not match any binary? If the input matches no exact route or alias, the router attempts a prefix listing. For example, entering `omarchy hw asus` when no `omarchy-hw-asus` binary exists will display all available commands matching the `omarchy-hw-asus-*` pattern, helping you discover the correct sub-command. ### Why does the Omarchy router use `exec` instead of spawning a subprocess? The `exec` system call replaces the router process entirely with the target binary, which ensures that the helper command's exit code becomes the exit code of the original `omarchy` invocation. This design makes the router transparent to shell scripts that check return values for error handling or conditional logic. ### How can I add a custom command to the Omarchy CLI? Create an executable file in the `bin/` directory with a name following the `omarchy--` convention. Include a `# omarchy:summary=` comment near the top of the file so the router can display it in help output. The new command will be available immediately without restarting the router or modifying configuration files.