How Omarchy's CLI Router Dispatches Commands: A Deep Dive into Dynamic Command Routing

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:<key>=<value>, 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 <group> <command> 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:

omarchy commands --all

Show detailed help for a specific command:

omarchy update --help

Generate JSON metadata for tooling integration:

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:

$ 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:<key>=<value> 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=<name> 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.

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