# How Does the Omarchy CLI Router Work? A Deep Dive into the Bash-Based Command Router

> Discover how the Omarchy CLI router uses Bash to auto-discover commands, parse metadata, and execute with longest-prefix matching. Learn the inner workings of this powerful command router.

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

---

**The Omarchy CLI router is a single Bash script (`bin/omarchy`) that auto-discovers every `omarchy-*` executable in its directory, registers commands via metadata parsing, and resolves invocations using a longest-prefix matching algorithm with a fast-path execution loop.**

This article explains the internal mechanics of the Omarchy command-line interface routing system, as implemented in the [omacom/omarchy](https://github.com/omacom/omarchy) repository. The router enables a clean subcommand structure (`omarchy theme set`, `omarchy update aur`) without requiring each command to reimplement argument parsing or help generation.

## Command Registration: Discovering and Indexing Binaries

The Omarchy CLI router begins by scanning its own directory for any executable file matching the pattern `omarchy-*`. Each discovered binary undergoes metadata extraction and route registration.

### Metadata Extraction from Comment Headers

For every `omarchy-*` file found, the router reads the first 80 lines searching for **metadata directives** in the format `# omarchy:key=value`. Supported keys include `group`, `name`, `summary`, `alias`, `args`, and `hidden` ([source](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy#L44-L104)).

```bash

# Example metadata block in bin/omarchy-theme-set:

# omarchy:group=theme

# omarchy:name=set

# omarchy:summary=Apply a color theme

# omarchy:args=THEME_NAME

```

### Fallback Route Derivation

When metadata is absent or incomplete, the router derives a **fallback route** directly from the filename. It splits on the first hyphen to determine the group, then converts remaining hyphens to spaces for the name ([source](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy#L53-L62)):

| Filename | Derived Group | Derived Name |
|----------|---------------|--------------|
| `omarchy-theme-set` | `theme` | `set` |
| `omarchy-update-aur` | `update` | `aur` |
| `omarchy-commands` | `commands` | *(empty)* |

### Route Registration and Collision Handling

Every command receives **two route entries**: the canonical route (after metadata overrides) and the filename-based route. Aliases create additional entries flagged as `IS_ALIAS=true`. When collisions occur—two different binaries registering the same route—the first registration wins and the conflict is logged for later inspection ([source](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy#L50-L66)).

## Fast-Path Resolution: Direct Binary Execution

The Omarchy CLI router prioritizes performance through a **fast-path resolution** mechanism that bypasses metadata lookups entirely. When arguments arrive, the router immediately constructs a candidate binary name:

```bash
route="omarchy $(join_words " " "${args[@]:0:prefix_count}")"
binary="omarchy-$(join_words "-" "${args[@]:0:prefix_count}")"

```

If `bin/$binary` exists, the router executes it directly with remaining arguments ([source](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy#L97-L107)). This hot-path optimization ensures common commands like `omarchy theme set dracula` launch without metadata overhead.

### Fast-Path Execution Example

```bash

# Router skips metadata, execs bin/omarchy-theme-set immediately

omarchy theme set dracula

```

## Fallback Resolution: Longest-Prefix Matching

When no direct binary match exists, the router falls back to **full metadata-driven resolution**:

1. Load all command metadata via `load_commands`
2. Iterate through argument prefixes from longest to shortest
3. Query the `ROUTE_TO_KEY` associative array for a registered match ([source](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy#L118-L130))

This longest-prefix algorithm enables flexible command structures where partial matches resolve correctly:

```bash

# Registered: omarchy theme set

# Invoked:    omarchy theme

# Result:     Group help for 'theme' (partial match, no binary)

```

## Help System and Argument Guarding

The Omarchy CLI router provides integrated help handling without requiring individual binaries to implement flag parsing.

### Automatic Help Detection

The router scans remaining arguments for `--help` or `-h` anywhere in the command line (`remaining_has_help_flag`). When found, it displays the command's metadata rather than executing the binary ([source](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy#L81-L89)).

```bash

# Help requested after subcommand argument

omarchy update aur --help

# → Shows help for 'update', not 'aur'

```

### JSON Output Mode

Adding `--json` to a help request switches output to machine-readable format:

```bash
omarchy theme list --help --json

# → {"group":"theme","name":"list","summary":"..."}

```

### Argument Validation

Commands declare required arguments via the `args` metadata key. When invoked without sufficient arguments, the router displays usage and exits—preventing incomplete executions:

```bash
omarchy theme set

# → Usage: omarchy theme set THEME_NAME

```

### Group Help Generation

Invoking a group without a subcommand triggers synthesized help built from the `GROUP_DESCRIPTIONS` table ([source](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy#L27-L38)):

```bash
omarchy theme

# → Lists all theme subcommands with summaries

```

## Hidden Commands and Collision Detection

The Omarchy CLI router supports **hidden commands** via `# omarchy:hidden=true`. These commands remain invocable but exclude themselves from listings and group help.

Registered collisions are tracked throughout the registration phase. The `omarchy commands --check` subcommand reports any conflicts discovered, enabling debugging of route overlap during development ([source](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy#L56-L60)).

## Error Handling and Command Suggestions

When resolution fails entirely, the Omarchy CLI router provides intelligent assistance through prefix-based suggestion matching (`suggest_command`):

```bash
omarchy tme --help

# Output:

#   Unknown Omarchy command: omarchy tme

#   Did you mean: omarchy theme ?

#   Run 'omarchy commands --all' to discover available commands.

```

The suggestion algorithm finds the closest registered route by prefix similarity, reducing friction for typos and incomplete commands ([source](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy#L133-L145)).

## Flag Handling Edge Cases

The router implements POSIX-compatible flag termination with `--`. Everything following a bare double-dash is forwarded to the target binary unprocessed, allowing commands to receive their own flag sequences:

```bash
omarchy theme set -- --force --verbose=2

# → bin/omarchy-theme-set receives: --force --verbose=2

```

## Practical Examples

```bash

# Fast-path execution (no metadata lookup)

omarchy theme set dracula

# Help with JSON output

omarchy config get --help --json

# Hidden command (works, but unlisted)

omarchy internal-debug logs

# Force argument passthrough

omarchy pkg search -- --regex '^vim-'

```

## Summary

- **Single-script architecture**: The entire Omarchy CLI router lives in `bin/omarchy`, approximately 80 lines of registration logic plus resolution and help generation.
- **Metadata-driven registration**: Commands self-describe via `# omarchy:key=value` comments in their first 80 lines, enabling dynamic discovery without configuration files.

- **Dual-route system**: Each command registers both canonical (metadata-override) and fallback (filename-derived) routes.
- **Fast-path optimization**: Direct binary existence checks bypass metadata lookups for the common case.
- **Longest-prefix fallback**: Partial matches resolve through iterative prefix reduction against the route table.
- **Integrated help system**: Automatic `--help`/`-h` detection, JSON mode, and argument validation without binary cooperation.
- **Developer tooling**: Collision detection via `omarchy commands --check` and typo suggestions for unknown commands.

## Frequently Asked Questions

### How does the Omarchy CLI router handle command conflicts?

When two binaries register identical routes, the **first registration wins** and subsequent attempts are logged as collisions. Run `omarchy commands --check` to inspect any conflicts detected during router initialization. This design prioritizes stability—commands continue working while developers receive visibility into overlaps.

### Can I override the route derived from my command's filename?

Yes. Specify `# omarchy:group=VALUE` and `# omarchy:name=VALUE` in your command's comment header. These metadata directives override the automatic fallback route while preserving the filename route as a secondary entry. Aliases (`# omarchy:alias=ALTERNATE_NAME`) create additional route mappings flagged separately.

### What happens if I type a command that doesn't exist?

The Omarchy CLI router executes a **prefix-matching suggestion algorithm** (`suggest_command`) and displays the closest registered route with a "Did you mean?" prompt. If no reasonable match exists, it directs you to `omarchy commands --all` for discovery. This behavior is implemented in `bin/omarchy` lines 133–145.

### Why does `omarchy theme set --help` show help for `theme` instead of `set`?

The router scans **all remaining arguments** for `--help` or `-h` after resolving the command prefix. In `omarchy theme set --help`, the longest-prefix match is `omarchy theme`, so the `theme` group's metadata is displayed. To get help for `set` specifically, use `omarchy theme set -- --help` (with `--` to pass the flag through) or consult `omarchy commands --all`.