# Understanding the Omarchy CLI Commands Dispatch Mechanic > Discover how the Omarchy CLI dispatches commands. Learn about its fast path execution and metadata-driven route resolution for aliases and complex mappings. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: internals - Published: 2026-08-29 --- **The Omarchy CLI uses a central router script at `bin/omarchy` that dispatches commands by joining arguments with hyphens to locate matching executables in a fast path, falling back to metadata-driven route resolution for aliases and complex mappings.** The Omarchy command-line interface implements a unique dispatch system where a single router binary coordinates execution across numerous specialized scripts. According to the basecamp/omarchy source code, this design separates routing logic from command implementation, enabling both high-performance execution and dynamic route configuration. Understanding the Omarchy CLI commands dispatch mechanic reveals how the system balances speed with flexibility through intelligent path resolution and metadata-aware routing. ## The Router Architecture and File Structure The dispatch system centers on the `bin/omarchy` router, which acts as the sole entry point for all CLI operations. This router translates space-separated command lines into the flat executable namespace provided by the many `bin/omarchy-*` scripts distributed throughout the repository. ### Routing Rules and Namespace Mapping When the router processes a command, it derives a **group** and **name** from the executable filename by splitting on the first hyphen after the `omarchy-` prefix. For example, `bin/omarchy-theme-set` maps to group `theme` and name `set`. As documented in [`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md) (lines 14-27), the system registers both a **canonical route** (`omarchy `) and a **filename route** where every hyphen becomes a space. Command authors can override these default routes or add aliases by embedding metadata in file headers. The specification for this metadata lives in [`agents/skills/command-metadata.md`](https://github.com/basecamp/omarchy/blob/main/agents/skills/command-metadata.md), allowing scripts to declare custom names without renaming the physical file. ## Fast-Path Dispatch Algorithm For common invocations, the router employs a performance-optimized **fast path** that avoids parsing metadata entirely. When a user invokes `omarchy` with arguments, the router joins those arguments with hyphens and checks for the existence of a matching executable in sequence. For instance, executing `omarchy theme set foo` causes the router to search for `bin/omarchy-theme-set-foo` first, then fall back to `bin/omarchy-theme-set` if the former does not exist (docs/cli-router.md, lines 49-57). If a matching file is found, the router immediately executes it via `exec`, passing any leftover arguments directly to the target binary. This file-system-first approach eliminates overhead for the majority of commands. ## Metadata-Driven Route Resolution When the fast path fails to locate an executable—such as when a command has been renamed via metadata or invoked through an alias—the router activates its **metadata fallback** mechanism. This process lazily loads metadata from all command files, builds a comprehensive route table, and resolves the request using **longest-prefix matching**. As implemented in the basecamp/omarchy source code (docs/cli-router.md, lines 62-66), the router drops trailing words from the argument list until it finds a registered route. Once matched, it executes the corresponding binary with the remaining words passed as arguments. This enables flexible routing schemes where a single binary can handle multiple subcommands or respond to alternative names defined in comment headers. ## Help Flag Interception and Argument Passing The router provides universal help handling by intercepting `--help` or `-h` flags wherever they appear in the argument stream. This allows users to request help at any position in the command line without the target binary executing. However, the system respects the `--` separator to disambiguate flags meant for the target command. When the router encounters `--`, it stops scanning for help flags and passes all subsequent arguments verbatim to the underlying binary (docs/cli-router.md, lines 67-74). This ensures that flags like `--help` can still be passed to subcommands when explicitly shielded by the separator. ## Execution Model and Error Handling Dispatch operations use the `exec` system call, which replaces the router process entirely with the target binary. This design means the router process does not persist after handing off control, ensuring minimal resource overhead. The target binary receives only the leftover arguments determined during route resolution. If the router cannot resolve any route for the provided arguments, it exits with status code **127** and provides helpful feedback. According to the source in [`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md) (lines 82-89), the system suggests possible completions or prints "did you mean" hints, directing users to `omarchy commands --all` for a complete listing. ## Practical Dispatch Examples The following examples demonstrate the dispatch mechanic in action: ```bash # Fast-path dispatch to a simple command $ omarchy theme set dark # Router executes bin/omarchy-theme-set with argument "dark" ``` ```bash # Metadata-driven alias resolution # File bin/omarchy-install-gaming-xbox-cloud contains: # # omarchy:name=gaming xbox-cloud $ omarchy install gaming xbox-cloud # Resolves via metadata and executes the same binary ``` ```bash # Passing flags to subcommands using -- separator $ omarchy update aur -- --dry-run # Router stops scanning at --; "--dry-run" is passed to the aur subcommand ``` ```bash # Automatic help interception $ omarchy update aur --help # Displays help for the aur subcommand without executing it ``` ## Summary - The `bin/omarchy` router serves as the central dispatcher, translating user input into executable paths through hyphen-joined filename matching. - **Fast-path dispatch** checks for literal file matches before loading metadata, optimizing performance for standard invocations. - **Metadata fallback** enables aliases and custom routes via comment headers, with resolution following longest-prefix matching rules. - Help flags (`--help`, `-h`) are intercepted globally unless protected by the `--` separator, which forces literal argument passing. - Unresolved routes result in exit code 127 with suggestions for available commands, while successful dispatches use `exec` to replace the router process entirely. ## Frequently Asked Questions ### How does the Omarchy router handle command aliases? Aliases are defined through metadata comments in the command file headers, as specified in [`agents/skills/command-metadata.md`](https://github.com/basecamp/omarchy/blob/main/agents/skills/command-metadata.md). When the fast path fails, the router loads this metadata to build a route table that maps alternative names to their canonical executables, enabling flexible command structures without file duplication. ### What happens when the router cannot find a matching command? If no executable matches the hyphen-joined arguments and metadata resolution fails, the router exits with status code 127. It then suggests possible completions or directs the user to `omarchy commands --all` to discover available commands, providing a helpful debugging path for typos or missing installations. ### How are command-line flags passed to target binaries? The router passes all arguments following the matched route directly to the target executable. However, it intercepts `--help` and `-h` flags unless they appear after a `--` separator, which terminates the router's flag scanning. This allows precise control over whether flags are handled by the router or forwarded to the command. ### Where is the dispatch logic documented in the source code? The primary documentation resides in [`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md), which details the routing rules, dispatch algorithm, and help handling mechanisms. The metadata specification for command headers is located in [`agents/skills/command-metadata.md`](https://github.com/basecamp/omarchy/blob/main/agents/skills/command-metadata.md), while the actual router implementation is contained in the executable `bin/omarchy`.