How the `bin/omarchy` CLI Router Dispatches Commands: Dynamic Routing in Omarchy

The bin/omarchy CLI router is a Bash-based command dispatcher that dynamically discovers executables, parses metadata headers to build route tables, and resolves commands through a two-phase lookup system combining fast-path binary matching with full-route progressive resolution.

The bin/omarchy CLI router serves as the central nervous system of the Omarchy framework, eliminating the need for hardcoded command lists by automatically discovering capabilities at runtime. Written entirely in Bash, this router scans for omarchy-* executables, extracts structured metadata from comment headers, and maintains associative arrays that map user-facing routes to their underlying binaries.

Dynamic Command Discovery and Registration

The router initializes its command registry through the load_commands function, which iterates over every executable named omarchy-* in the same directory as the main router script. For each binary discovered, the router invokes register_command to parse metadata comments formatted as # omarchy:<key>=<value>.

This registration process builds several associative arrays that store:

• Binary-to-route mapping (e.g., omarchy-update maps to omarchy update)
• Group classifications for organizing related commands
• Command summaries and argument specifications
• Explicit aliases for alternative command names

All discovery and registration logic executes early in the script lifecycle, populating the routing tables before any user input is processed. This metadata-driven approach allows the system to recognize new commands immediately upon installation without requiring router modifications.

Fast-Path Resolution for Direct Binary Matches

When a user invokes omarchy <args>, the entry point main delegates to dispatch_fast_or_help for initial route resolution. This function implements an optimized lookup via resolve_direct_route, which searches for a binary whose name matches the longest possible prefix of the provided arguments.

For example, when executing omarchy snapshot create, the fast-path attempts to locate omarchy-snapshot first. If found, the router examines the remaining arguments (create) for help flags (--help or -h) or JSON output requests (--json).

The fast-path handles several edge cases:

• Help flag detection: If --help is present, the router loads the command's metadata (if not cached) and renders detailed usage information via show_command_help or show_command_json
• Argument validation: When no arguments remain but the command expects them, the router displays short help rather than executing the binary
• Group-level fallback: If no direct binary match exists, the fast-path yields to group-level handling (e.g., omarchy update where update functions as a command group)

Full-Route Resolution and Fallback Handling

If the fast-path fails to resolve a binary, the router escalates to dispatch_or_help, which performs comprehensive route resolution through resolve_route. This function constructs candidate routes by progressively reducing the argument prefix until a registered route is located, effectively handling complex subcommand hierarchies like omarchy theme set.

Once a route resolves, the same help-handling and validation logic applies, culminating in binary execution via the exec builtin for optimal performance. If resolution fails entirely, the router invokes show_prefix_help or suggest_command to provide contextual error messages and suggest closest matches based on registered commands.

Example Command Flows

The router handles various invocation patterns automatically:

# Dynamic discovery of all available commands

omarchy commands --all

# Detailed help generation from parsed metadata

omarchy update --help

# JSON metadata export for external tooling integration

omarchy theme set --json

# Direct binary execution after route resolution

omarchy snapshot create

Behind the scenes, omarchy snapshot create executes as follows:

1. dispatch_fast_or_help calls resolve_direct_route → locates omarchy-snapshot binary
2. Remaining args (create) contain no help flags → validation passes
3. Router executes exec /usr/share/omarchy/bin/omarchy-snapshot create

For mistyped commands, the suggestion system activates:

$ omarchy updat
Unknown Omarchy command: omarchy updat
Did you mean: omarchy update ?
Run 'omarchy commands --all' to discover available commands.

Summary

• Discovery Phase: The load_commands and register_command functions in bin/omarchy scan omarchy-* executables and parse # omarchy:key=value metadata headers to build routing tables

• Fast-Path Resolution: dispatch_fast_or_help leverages resolve_direct_route for O(1) binary prefix matching, handling help flags and argument validation before execution

• Full-Route Resolution: dispatch_or_help uses resolve_route to progressively match complex subcommand paths and aliases when fast-path lookup fails

• Execution Model: Validated commands launch via exec for process replacement, while failures trigger suggest_command for typo correction or show_prefix_help for contextual assistance

Frequently Asked Questions

How does the bin/omarchy router discover new commands without configuration files?

The router performs filesystem scanning at startup. The load_commands function iterates over all omarchy-* executables in the bin/ directory, and register_command parses structured metadata comments (such as # omarchy:group=system or # omarchy:summary=Updates the system) to build routing tables dynamically. This eliminates the need for static command registries or configuration files when adding new functionality.

What distinguishes fast-path resolution from full-route resolution?

Fast-path resolution via resolve_direct_route attempts direct binary prefix matching (e.g., mapping omarchy update to the omarchy-update binary) for immediate execution. Full-route resolution via resolve_route activates when fast-path fails, progressively reducing argument prefixes to match registered routes including groups and aliases. The two-phase approach optimizes performance for common direct commands while supporting complex nested subcommands.

How does the router handle mistyped or unknown commands?

When route resolution fails, the router invokes suggest_command to calculate and display the closest matching registered command (using string similarity algorithms). If the input matches a known group prefix, show_prefix_help displays available subcommands within that group. This ensures users receive actionable guidance rather than generic errors.

Can external tools programmatically consume Omarchy command metadata?

Yes. The router exposes structured metadata via the --json flag supported by the help system. When invoked as omarchy <command> --json, the router outputs parsed metadata including groups, summaries, arguments, and aliases in JSON format, enabling IDE integrations, shell completion generators, and documentation tools to consume command definitions directly from the source of truth.

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