# How Omarchy CLI Command Center Routing Works: A Deep Dive into the Bash Router

> Discover how Omarchy's pure Bash router dynamically routes CLI commands. Learn about metadata parsing and efficient dispatch to binaries via associative arrays.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: deep-dive
- Published: 2026-08-30

---

**Omarchy's CLI command center uses a pure-Bash router that dynamically discovers executables in `bin/`, parses structured metadata from comment headers, and dispatches user requests to the appropriate binary via fast associative-array lookups.**

Omarchy's command-line interface eliminates hardcoded command lists by implementing a self-discovering routing system. According to the omacom/omarchy source code, the central router in `bin/omarchy` builds a lightweight command registry at runtime, parsing special `# @omarchy:` metadata blocks to automatically generate help text and resolve routes.

## Phase 1: Loading and Registering Commands

The routing process begins when the `load_commands` function scans every file in `$OMARCHY_BIN_DIR` (typically `bin/`), excluding the router itself.

### Scanning bin/ and Parsing Metadata

For each executable discovered, the router invokes `register_command` (lines 168-190 in `bin/omarchy`). This function reads the first 80 lines of the file (defined by the constant `METADATA_SCAN_LIMIT`) searching for comment lines starting with `# @omarchy:`.

The parser extracts these metadata fields:

- **`group`** – Logical categorization for help organization
- **`name`** – Short command identifier  
- **`summary`** – One-line description
- **`usage`** – Full syntax string including positional arguments
- **`args`** – Argument placeholders
- **`examples`** – Pipe-separated usage examples
- **`aliases`** – Alternative command names
- **`requires_sudo`** – Elevation requirements flag
- **`hidden`** – Visibility in default command listings

After extraction, the function populates associative arrays including `COMMAND_ROUTE`, `COMMAND_GROUP`, and `COMMAND_USAGE`.

### Route Registration

Once metadata is parsed, `register_route` (lines 150-166) maps the textual route (e.g., `theme set`) to an internal key in the `ROUTE_TO_KEY` array. The system enforces route uniqueness; duplicate routes are recorded in `ROUTE_COLLISIONS` for debugging.

## Phase 2: Resolving the Request

When a user executes `omarchy <tokens...>`, control passes to `dispatch_fast_or_help` (lines 887-904).

### Fast Route Resolution

The router first attempts `resolve_fast_route`, which performs a longest-prefix match against the `ROUTE_TO_KEY` associative array. It walks the token list sequentially, checking for valid route matches at each depth.

If the resolved route points to a concrete binary, `resolve_binary` locates the executable path. If the route resolves only to a group (e.g., `omarchy theme` without a subcommand), the system invokes `show_group_help` to display categorized available commands.

### Global Flag Detection

Before execution, the router inspects remaining arguments using `remaining_has_help_flag` and `remaining_has_json_flag` (lines 128-146). These helpers detect `--help`, `-h`, and `--json` flags early, ensuring they pass through to the target binary unchanged for native handling.

## Phase 3: Execution or Fallback

### Binary Execution

When a valid binary is resolved, the router executes:

```bash
exec "$binary_path" "${remaining[@]}"

```

This replaces the current process with the target command, forwarding any unparsed arguments directly.

### Unknown Command Handling

If `resolve_fast_route` fails to find a match, the router prints "Unknown Omarchy command" and invokes `suggest_command` (lines 610-671). This fuzzy matching algorithm compares the input against known command keys to suggest the closest alternative. The process exits with status **127** to indicate command not found, prompting users to run `omarchy commands --all` for discovery.

## Metadata Format for Command Authors

To participate in the routing system, command scripts must include metadata headers:

```bash
#!/bin/bash

# @omarchy: group=theme

# @omarchy: name=set

# @omarchy: summary=Apply a theme to Omarchy

# @omarchy: usage=omarchy theme set <theme-name>

# @omarchy: args=<theme-name>

# @omarchy: examples=omarchy theme set dracula|omarchy theme set nord

# @omarchy: hidden=false

```

The router discovers this automatically when `load_commands` runs, requiring no modifications to the central router code when adding new functionality.

## Summary

- **Omarchy's CLI uses a pure-Bash router** located in `bin/omarchy` that discovers commands dynamically from the `bin/` directory.
- **Metadata-driven registration** parses `# @omarchy:` comments to populate associative arrays like `COMMAND_ROUTE` and `COMMAND_GROUP`.

- **Fast resolution** uses `resolve_fast_route` to match the longest valid prefix against the `ROUTE_TO_KEY` registry.
- **Transparent flag passing** ensures `--help` and `--json` flags reach target binaries for native processing.
- **Fuzzy fallback** via `suggest_command` provides intelligent suggestions when users mistype commands, exiting with code 127.

## Frequently Asked Questions

### How does Omarchy discover new commands without modifying the router?

The `load_commands` function scans the `bin/` directory at runtime, automatically registering any executable containing valid `# @omarchy:` metadata headers. This allows developers to add commands simply by placing new scripts in the directory without touching the central router logic in `bin/omarchy`.

### What happens when I type an incomplete command like `omarchy theme`?

The router resolves `theme` as a group route without a concrete binary, triggering `show_group_help` to display all available subcommands within that group, such as `theme set` or `theme list`.

### Why does the router use `exec` instead of spawning a subprocess?

The `dispatch_fast_or_help` function uses `exec "$binary_path" "${remaining[@]}"` to replace the current shell process with the target binary. This eliminates overhead, ensures signals propagate correctly, and preserves exit codes while forwarding all remaining arguments untouched.

### How does the suggestion algorithm work for misspelled commands?

When `resolve_fast_route` fails, the `suggest_command` function (located around lines 610-671) performs fuzzy string matching against registered command keys in the associative arrays. It calculates similarity between the input tokens and known routes, offering the closest match before exiting with status 127.