Understanding the Omarchy CLI Commands Dispatch Mechanic

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 (lines 14-27), the system registers both a canonical route (omarchy <group> <name>) 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, 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 (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:

# Fast-path dispatch to a simple command

$ omarchy theme set dark

# Router executes bin/omarchy-theme-set with argument "dark"

# 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

# Passing flags to subcommands using -- separator

$ omarchy update aur -- --dry-run

# Router stops scanning at --; "--dry-run" is passed to the aur subcommand

# 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. 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, 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, while the actual router implementation is contained in the executable bin/omarchy.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}