# How Omarchy's CLI Router Dispatches Commands: A Deep Dive into Dynamic Command Routing > Discover how Omarchy's CLI router dynamically dispatches commands by scanning for executables, parsing metadata, and using a two-stage resolution strategy for efficient execution and automatic help generation. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: deep-dive - Published: 2026-08-25 --- **Omarchy's CLI router dynamically discovers sub-commands by scanning for `omarchy-*` executables, parses metadata comments to build routing tables, and employs a two-stage resolution strategy—fast-path direct matching followed by full-route progressive reduction—to execute binaries with automatic help generation.** The `omarchy` executable in the Basecamp Omarchy repository implements a sophisticated Bash-based command dispatcher. Understanding how Omarchy's CLI router dispatches commands reveals a pattern for building self-documenting, discoverable shell tools that require zero manual registration when adding new functionality. ## Dynamic Command Discovery and Registration The router begins by building a comprehensive registry of available commands through filesystem scanning and metadata parsing. In `bin/omarchy`, the `load_commands` function iterates over every executable named `omarchy-*` in the same directory. For each binary discovered, it invokes `register_command` to extract configuration data embedded within the file as structured comment headers. The metadata follows the format `# omarchy:=`, defining properties such as: - **Route mapping**: Links the binary (e.g., `omarchy-update`) to its invocation path (e.g., `omarchy update`) - **Grouping**: Organizes commands into logical categories (e.g., `system`, `development`) - **Documentation**: Stores summaries, argument specifications, and descriptions - **Aliases**: Registers alternative names for the same command This registration process executes early in the script lifecycle (see the implementation at lines 12-19 in `bin/omarchy`), populating associative arrays that serve as the routing table for subsequent dispatch operations. ## Two-Stage Command Resolution When you invoke `omarchy` with arguments, the router attempts resolution through two complementary strategies, starting with the fastest path and falling back to a more thorough search if needed. ### Fast-Path Resolution via `resolve_direct_route` The `dispatch_fast_or_help` function (lines 946-989 in `bin/omarchy`) implements the primary resolution logic. It first calls `resolve_direct_route`, which performs a **longest prefix match** against the provided arguments. For example, when you run `omarchy snapshot create`, the resolver looks for a binary named `omarchy-snapshot`. If found, it examines the remaining arguments (`create`) for help flags (`--help` or `-h`) or JSON output requests (`--json`). If help flags are detected, the router loads the command's metadata and renders formatted documentation via `show_command_help` or `show_command_json`. If the command requires arguments but none are provided, it displays concise usage information rather than executing the binary. When the first argument matches a group name rather than a specific binary (e.g., `omarchy update` where `update` represents a category), the fast-path gracefully falls back to group-level handling. ### Full-Route Resolution via `resolve_route` If the fast-path fails to locate a matching binary, `dispatch_or_help` (lines 1010-1068 in `bin/omarchy`) initiates the full-route resolution process. This calls `resolve_route`, which constructs candidate routes by progressively reducing the argument prefix until it finds a registered match. The algorithm attempts combinations like `omarchy ` against the routing table, checking for exact matches and registered aliases. Once a route resolves, the same validation and help-handling logic applies, culminating in an `exec` call to the target binary with the remaining arguments. If no route matches, the router provides intelligent fallbacks: `show_prefix_help` displays available commands sharing the same prefix, while `suggest_command` offers the closest matching alternative based on string similarity. ## Command Execution Flow and Examples The entry point `main` function (lines 1070-1088 in `bin/omarchy`) directs traffic either to `dispatch_fast_or_help` for normal command routing or to the `commands` sub-command for metadata listings. List all available commands including hidden ones: ```bash omarchy commands --all ``` Show detailed help for a specific command: ```bash omarchy update --help ``` Generate JSON metadata for tooling integration: ```bash omarchy theme set --json ``` When you execute `omarchy snapshot create`, the router performs these steps: 1. `dispatch_fast_or_help` calls `resolve_direct_route`, locating `bin/omarchy-snapshot` 2. Detects `create` as a sub-command argument without help flags 3. Executes `exec /usr/share/omarchy/bin/omarchy-snapshot create` directly For mistyped commands, the suggestion engine activates automatically: ```bash $ omarchy updat Unknown Omarchy command: omarchy updat Did you mean: omarchy update ? Run 'omarchy commands --all' to discover available commands. ``` ## Summary - **Discovery mechanism**: The `load_commands` and `register_command` functions in `bin/omarchy` scan for `omarchy-*` binaries and parse `# omarchy:=` metadata to construct routing tables. - **Fast-path routing**: `dispatch_fast_or_help` uses `resolve_direct_route` to match the longest binary prefix and immediately execute matching commands. - **Full-resolution fallback**: `dispatch_or_help` employs `resolve_route` to progressively reduce argument prefixes and locate complex group/command hierarchies. - **Self-documenting behavior**: The router automatically generates help output, validates required arguments, and suggests corrections for unknown commands without additional configuration. - **Zero-registration design**: New commands become available immediately when added to the `bin/` directory with appropriate metadata headers. ## Frequently Asked Questions ### How does Omarchy automatically detect new sub-commands? The router scans the executable directory for files matching the pattern `omarchy-*` during initialization. When it finds a new binary, `register_command` parses the metadata comments and adds the command to the internal routing table. This means adding a new executable to `bin/` with the proper `# omarchy:` headers automatically makes it available through the CLI without modifying the dispatcher code. ### What happens when I run `omarchy` with the `--help` flag? The router intercepts `--help` or `-h` during both the fast-path (`dispatch_fast_or_help`) and full-resolution (`dispatch_or_help`) phases. Before executing any binary, it checks the remaining arguments for help flags. If detected, the system loads the command's metadata and renders detailed usage information via `show_command_help`, displaying arguments, descriptions, and available aliases rather than running the command. ### How does the router handle typos or unknown commands? When `resolve_route` fails to find a matching binary or registered alias, the dispatcher calls `suggest_command` to calculate string similarity between the mistyped input and available commands. It then displays the closest match (e.g., "Did you mean: omarchy update?") and suggests running `omarchy commands --all` to browse available options. For partial matches, `show_prefix_help` lists all commands sharing the typed prefix. ### Can I add aliases for Omarchy commands? Yes. During the registration phase in `bin/omarchy`, the `register_command` function processes metadata headers that define explicit aliases. By including `# omarchy:alias=` comments in your `omarchy-*` executable, the router creates additional route mappings that point to the same binary. These aliases participate fully in help generation and command resolution, allowing multiple invocation patterns for the same underlying functionality.