# How Omarchy's CLI Routing System Works Internally: A Deep Dive into the Dispatcher > Discover how Omarchy's CLI routing system works internally with a deep dive into its two-stage dispatch mechanism. Learn about filename matching and metadata-driven lookups. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: internals - Published: 2026-08-18 --- **Omarchy's CLI uses a two-stage dispatch mechanism where the `bin/omarchy` dispatcher first attempts a fast filename match against `omarchy-*` binaries, then falls back to a full metadata-driven route table lookup built from header comments in each executable.** The Omarchy command-line interface follows a unique convention-driven architecture that transforms filenames into command hierarchies. Located in the `basecamp/omarchy` repository, the routing system treats every executable matching the `omarchy-*` pattern as a potential command, parsing metadata from the first 80 lines of each file to build a dynamic route table. This design enables zero-configuration command discovery while maintaining low-latency dispatch through intelligent caching strategies. ## Binary-to-Route Mapping and Filename Conventions The routing system in `bin/omarchy` treats every executable file prefixed with `omarchy-` as a command candidate. The dispatcher derives routes by splitting the filename at hyphens to establish command groups and names. When processing a filename like `omarchy-theme-set`, the dispatcher splits at the first hyphen to obtain group **theme** and name **set**. Remaining hyphens become spaces, so `omarchy-hw-asus-rog` maps to the route `omarchy hw asus rog`. A binary without extra hyphens, such as `omarchy-update`, becomes the root command of its own group with an empty name. Each binary registers two distinct routes: - **Canonical route**: The processed route `omarchy ` after applying any metadata overrides via the `# omarchy:name=` comment directive. - **Filename route**: The route derived directly from the filename with hyphens converted to spaces. If metadata moves the name—for example, `# omarchy:name=gaming xbox-cloud` embedded in `omarchy-install-gaming-xbox-cloud`—both the canonical route (`omarchy install gaming xbox-cloud`) and the original filename route (`omarchy install gaming xbox cloud`) resolve to the same binary. An explicit empty name (`# omarchy:name=`) designates the command as the group's root, allowing `omarchy-menu-share` to resolve as `omarchy share`. ## Metadata Extraction from Command Headers The `register_command` function in `bin/omarchy` (source lines 87-104) scans only the first 80 comment lines of each binary to extract routing metadata. This keeps the startup sequence fast while allowing rich command definitions. Recognized metadata keys include: - `group` – Overrides the default group derived from the filename. - `name` – Overrides the default name or creates multi-word command names. - `summary` – Brief description shown in help listings. - `args` – Argument specification for validation. - `examples` – Usage examples displayed in help text. - `alias` or `aliases` – Additional routes that resolve to this command. - `requires-sudo` – Indicates if the command needs elevated privileges. - `hidden` – Excludes the command from standard listings unless `--all` is used. If no metadata is present, the system derives defaults strictly from the filename. Missing or malformed metadata is silently ignored, falling back to the filename route without breaking the dispatch chain. ## Route Table Construction During initialization, the `load_commands` function iterates over all `omarchy-*` executables in the path, invoking `register_command` for each binary. This process populates several associative arrays that form the complete routing infrastructure: - `COMMAND_ROUTE` – Stores the canonical route for each command. - `COMMAND_FALLBACK_ROUTE` – Stores the raw filename-derived route. - `COMMAND_BINARY` – Maps commands to their filesystem paths. - `COMMAND_GROUP`, `COMMAND_NAME`, `COMMAND_SUMMARY` – Store parsed metadata. - `ROUTE_TO_KEY` – Primary lookup table mapping route strings to command keys. - `ROUTE_IS_ALIAS` – Marks routes that function as aliases. - `ROUTE_COLLISIONS` – Tracks when multiple binaries claim the same route (first registration wins). This approach ensures that the `ROUTE_TO_KEY` table contains every valid path for command resolution, including aliases and fallback routes, enabling both exact matches and prefix-based lookups. ## The Two-Stage Dispatch Algorithm The dispatcher implements two distinct resolution paths to balance speed against flexibility. ### Fast Path: Direct Filename Resolution The `dispatch_fast_or_help` function provides the hot path for command execution. It calls `resolve_direct_route` to build candidate filenames by joining input arguments with hyphens and checking for executable files. For example, when executing `omarchy theme set dark`, the resolver checks for `bin/omarchy-theme-set-dark`, then `bin/omarchy-theme-set`. If found, the remaining arguments (`dark`) are passed directly to the binary. This path avoids loading any metadata, requiring only a few `stat` calls. It also handles help flags intelligently: if any remaining token is `--help` or `-h`, or if `command_requires_args` detects missing required arguments, the router loads the command's metadata and displays help instead of executing. ### Full Path: Metadata-Driven Resolution If the fast path fails to locate a binary, the router invokes `dispatch_or_help`, which loads all command metadata via `load_commands` and uses `resolve_route` to perform a longest-prefix match against the `ROUTE_TO_KEY` table. Once resolved, the system performs the same validation checks as the fast path using `remaining_has_help_flag` and `command_requires_args`. If validation passes, the dispatcher executes the binary via `exec`, replacing the shell process entirely. On failure, `suggest_command` provides typo correction by inspecting the route table for similar entries. ## Help System and Introspection The routing system exposes its internal state through several introspection commands that draw directly from the route table: - `omarchy commands` – Lists every non-hidden command using the `COMMAND_SUMMARY` array. - `omarchy commands --all` – Includes hidden commands in the output. - `omarchy commands --json` – Emits machine-readable JSON arrays of command records. - `omarchy commands --markdown` – Generates documentation-friendly output. - `omarchy commands --check` – Validates metadata consistency across all binaries. The top-level help interface, implemented in `show_main_help`, organizes commands by group using the `GROUP_DESCRIPTIONS` associative array defined in `bin/omarchy`. Because all help text pulls from the route table constructed at startup, documentation automatically reflects the current set of installed binaries without regeneration steps. ## Code Examples in Practice The following examples demonstrate the routing behavior: ```bash # Fast path: direct filename match $ omarchy theme set dark # → Executes bin/omarchy-theme-set with argument "dark" # Canonical route with metadata override # File: bin/omarchy-install-gaming-xbox-cloud contains: # # omarchy:name=gaming xbox-cloud $ omarchy install gaming xbox-cloud # → Executes bin/omarchy-install-gaming-xbox-cloud via canonical route # Help interception without execution $ omarchy theme set --help # → Loads metadata and displays summary/usage information # JSON introspection of the route table $ omarchy commands --json # → Outputs structured data including routes, summaries, and binary paths ``` ## Summary - **Filename convention**: Commands follow the `omarchy-*` pattern, with hyphens delimiting groups and subcommands. - **Dual registration**: Each binary registers both a canonical route (metadata-driven) and a fallback route (filename-driven). - **Metadata scope**: Only the first 80 lines are parsed for directives like `name`, `group`, `alias`, and `requires-sudo` via the `register_command` function. - **Fast dispatch**: The `dispatch_fast_or_help` path checks filesystem existence before loading any metadata, minimizing latency for common commands. - **Full resolution**: The `dispatch_or_help` path builds a complete route table in `ROUTE_TO_KEY` for prefix matching and alias support. - **Dynamic help**: All help output, including `omarchy commands --json`, reflects the live state of the `bin/` directory. ## Frequently Asked Questions ### How does Omarchy map filenames to CLI routes? Omarchy splits the filename after the `omarchy-` prefix at the first hyphen to determine the group and name. Additional hyphens become spaces in the route. For example, `omarchy-hw-asus-rog` becomes the route `omarchy hw asus rog`. The `register_command` function in `bin/omarchy` (lines 87-104) handles this parsing while checking for metadata overrides. ### What metadata keys does Omarchy support in command headers? The scanner recognizes `group`, `name`, `summary`, `args`, `examples`, `alias`, `aliases`, `requires-sudo`, and `hidden`. These are extracted from comment lines (starting with `#`) within the first 80 lines of the binary. If unspecified, the system derives `group` and `name` from the filename pattern. ### Why does Omarchy use a two-stage dispatch algorithm? The two-stage design optimizes for the common case where the command exists as a simple filename match. The `dispatch_fast_or_help` function checks filesystem existence without parsing metadata, executing in milliseconds. Only when this fails does the system incur the cost of building the full route table via `load_commands` and `resolve_route`, ensuring expensive operations occur only when necessary. ### How can I override the default route generated from a filename? Add a metadata comment specifying `# omarchy:name=` followed by your desired route segments separated by spaces. For example, placing `# omarchy:name=gaming xbox-cloud` in a file named `omarchy-install-gaming-xbox-cloud` makes `omarchy install gaming xbox-cloud` the canonical route while preserving the original filename route as an alias. To make a command the root of its group, use `# omarchy:name=` with an empty value.