# How the Omarchy CLI Command Router Works: File-System Driven Dispatch

> Discover how the Omarchy CLI command router uses a file-system driven approach with two-phase resolution for efficient command dispatch. Learn more about this lightweight dispatcher.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: internals
- Published: 2026-09-10

---

**The Omarchy CLI command router is a lightweight dispatcher that maps space-separated commands to executables in `bin/omarchy-*` using a two-phase resolution algorithm combining fast-path filename probing with lazy metadata-driven longest-prefix matching.**

The Omarchy CLI command router (implemented in `bin/omarchy` within the `omacom/omarchy` repository) eliminates traditional configuration files by deriving routes directly from filesystem patterns and embedded metadata. Unlike frameworks requiring explicit route registration, this system automatically discovers commands by scanning for binaries prefixed with `omarchy-`, translating human-readable arguments into executable calls through hyphen-joined filename matching.

## Route Registration and Discovery

### Executable Discovery Pattern

Every file in the `bin/` directory matching the `omarchy-*` glob automatically becomes a routable command. The stem following the `omarchy-` prefix determines the command's identity, while the router treats hyphens in the original filename as spaces for the **filename route** (e.g., `omarchy-theme-set` becomes `omarchy theme set`).

### Canonical vs. Filename Routes

The router registers two distinct route types for each binary:

- **Canonical route** — Derived from metadata comments (`# omarchy:group=…`, `# omarchy:name=…`) placed within the first 80 comment lines of the binary. This allows semantic naming independent of filesystem constraints.

- **Filename route** — Generated by converting hyphens to spaces in the actual filename.

Both routes remain active simultaneously, meaning a command responds to its canonical name and its filesystem-derived equivalent.

## Route Collision Handling

When multiple binaries claim identical routes, the router implements a **first-registration-wins** policy. The conflict is recorded internally for later auditing via `omarchy commands --check`, which reports overlapping route definitions to assist in debugging namespace collisions.

## The Dispatch Algorithm

The router employs a high-performance two-phase resolution strategy to minimize overhead:

### Phase 1: Fast-Path Filename Probe

The router joins supplied arguments with hyphens and probes for a matching executable. For example, invoking `omarchy theme set foo` triggers sequential checks for `bin/omarchy-theme-set-foo` followed by `bin/omarchy-theme-set`. This phase requires zero metadata parsing and serves as the hot path for common invocations.

### Phase 2: Metadata Fallback Resolution

If the fast-path probe fails, the router lazily loads command metadata from all binaries, constructs a comprehensive route table, and applies a **longest-prefix matching** rule. The longest matching prefix is selected as the target route; remaining arguments pass through to the executed binary.

## Guarded Execution and Error Handling

### Argument Validation

Commands declaring required arguments via the `args` metadata field trigger automatic help display when invoked without parameters, preventing malformed executions.

### Process Replacement and Exit Codes

Dispatch utilizes `exec` to replace the router process entirely with the target binary, ensuring exit codes propagate directly from the executed command. Unknown routes cause the router to terminate with exit code `127`.

### Special Flag Interception

The router intercepts `--help` and `-h` flags regardless of their position in leftover arguments, guaranteeing consistent help behavior. Adding `--json` to any command requests structured JSON output describing the command's interface.

## Prefix Listing and Route Suggestions

When resolution fails entirely, the router attempts **prefix listing** (e.g., `omarchy hw asus` lists all commands beginning with "hw asus") or suggests similar known routes, providing discoverability for partial matches without requiring exact syntax.

## Command Introspection

The router exposes several self-documenting interfaces for automation and discovery:

- `omarchy commands` — Lists every non-hidden command with its summary.
- `omarchy commands --all` — Includes hidden plumbing commands in the listing.
- `omarchy commands --json` — Exports the complete routing table including routes, binaries, groups, names, summaries, flags, arguments, examples, and aliases.
- `omarchy <route> --help` — Displays the resolved binary path and indicates when the filename route differs from the canonical route.

### Practical Usage Examples

```bash

# Simple dispatch using filename route

omarchy theme set dark            # Executes bin/omarchy-theme-set with argument "dark"

# Canonical route via metadata (binary: omarchy-install-gaming-xbox-cloud)

omarchy install gaming xbox-cloud   # Canonical route

omarchy install gaming xbox cloud   # Filename route still works

# Help interception works anywhere in argument list

omarchy update aur --help           # Resolves 'update' and forwards '--help'

# Prefix listing for partial matches

omarchy hw asus                    # Lists all commands starting with "hw asus"

# JSON introspection for tooling

omarchy commands --json            # Prints full routing table as JSON

```

### Key Implementation Files

- `bin/omarchy` — Core router script implementing the fast-path probe, lazy metadata loading, and `exec` dispatch.
- `bin/omarchy-*` — Individual command binaries where the filename determines the default route.
- [`docs/cli-router.md`](https://github.com/omacom/omarchy/blob/main/docs/cli-router.md) — Authoritative specification of the routing behavior and metadata format.
- [`agents/skills/command-metadata.md`](https://github.com/omacom/omarchy/blob/main/agents/skills/command-metadata.md) — Specification of metadata comment keys (`# omarchy:group`, `# omarchy:name`, etc.).

- `bin/omarchy` (`GROUP_DESCRIPTIONS` table) — Defines top-level group titles controlling which groups appear in the top-level help listing.

## Summary

- The Omarchy CLI router in `bin/omarchy` dispatches commands by mapping space-separated arguments to `bin/omarchy-*` executables using a **fast-path filename probe** followed by **lazy metadata resolution**.
- **Route registration** occurs automatically via filesystem scanning, supporting both metadata-defined canonical routes and hyphen-to-space filename routes derived from executable names.
- **Collision handling** uses first-registration-wins, with conflicts reported by `omarchy commands --check`.
- **Guarded execution** validates required arguments, uses `exec` for process replacement, and returns exit code `127` for unknown routes.
- **Introspection tools** provide JSON export (`--json`), prefix listing for partial matches, and help flag interception for enhanced discoverability.

## Frequently Asked Questions

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

When two binaries claim the same route, the first registered route takes precedence and subsequent collisions are recorded internally. Run `omarchy commands --check` to audit these conflicts and identify which binaries overlap in their route definitions.

### What happens if I type a partial command name?

The router attempts prefix matching when exact resolution fails. For example, entering `omarchy hw asus` lists all commands whose routes start with "hw asus", providing a discoverability mechanism for long command names without requiring full typing.

### Can I use the original hyphenated filename instead of the space-separated command?

Yes. Both styles work simultaneously because the router registers the **filename route** (hyphens as spaces) alongside any **canonical route** defined in metadata. A binary named `omarchy-install-gaming-xbox-cloud` responds to both `omarchy install gaming xbox-cloud` and `omarchy install gaming xbox cloud`.

### Where does the Omarchy CLI store its routing configuration?

The router requires no external configuration files. All routing information derives from two sources: the filesystem names of executables in `bin/omarchy-*` and metadata comments within the first 80 lines of those binaries (specifically `# omarchy:group=…` and `# omarchy:name=…` directives).