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

> Discover how bin/omarchy dynamically dispatches commands. Explore its two-phase lookup system, route tables, and fast-path binary matching for efficient CLI command resolution.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: internals
- Published: 2026-08-22

---

**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:

```bash

# 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:

```bash
$ 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.