# How Omarchy Resolves CLI Commands to Binaries: Fast‑Path and Metadata Routing

> Discover how Omarchy resolves CLI commands to binaries using fast-path and metadata routing. Learn about its efficient pattern probing and fallback mechanisms for seamless command execution.

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

---

**Omarchy resolves spaced commands like `omarchy theme set foo` to executable binaries by joining arguments with hyphens, probing for files matching the `omarchy-*` pattern, and falling back to metadata‑driven route tables when necessary.**

The `omacom/omarchy` repository implements a lightweight command‑line router that eliminates complex parsing by treating the filesystem as the source of truth. Instead of maintaining a central registry, the router discovers commands dynamically based on filenames and optional comment headers.

## The File Naming Convention That Defines Routes

Every executable file in the `bin/` directory that starts with `omarchy-` automatically registers one or more command routes. The router derives the **group** and **name** directly from the filename using a simple parsing rule:

- The characters after `omarchy-` are split at the first hyphen
- Everything before the first hyphen becomes the **group**
- Everything after becomes the **name**, with remaining hyphens converted to spaces

For example, `bin/omarchy-theme-set` registers the canonical route `omarchy theme set` because:
- Group: `theme`
- Name: `set` (derived from `set`)

The router also registers a *filename route* where every hyphen is replaced with a space, ensuring the textual command matches the binary exactly.

## Fast‑Path Resolution: Hyphen‑Joined Binary Probing

When you run a command, the router in `bin/omarchy` first attempts **fast‑path resolution** to minimize overhead. This method joins the supplied arguments with hyphens and checks for a matching executable file without reading any metadata.

```bash

# Inside dispatch_fast_or_help()

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

```

If you execute `omarchy theme set tokyo-night`, the router performs these probes:
1. `omarchy-theme-set-tokyo-night` → not found
2. `omarchy-theme-set` → found (`bin/omarchy-theme-set`)

The router then executes the binary with the remaining arguments:

```bash
exec bin/omarchy-theme-set tokyo-night

```

This approach requires only a few `stat` calls and avoids parsing comment headers entirely.

## Metadata‑Driven Fallback Routing

If the fast path fails to find a matching binary, the router loads **command metadata** from the first 80 lines of every `omarchy-*` script. According to the specification in [`agents/skills/command-metadata.md`](https://github.com/omacom/omarchy/blob/main/agents/skills/command-metadata.md), developers can override routes, define aliases, hide commands from help output, or add descriptions using structured comments.

After parsing metadata from all binaries, the router builds a route table (`ROUTE_TO_KEY`) and performs a longest‑prefix lookup via `resolve_route` (lines 119‑127 in `bin/omarchy`). This allows commands to expose multiple aliases without creating separate files.

## Dispatch Flow and Execution

The `omarchy` binary follows a strict dispatch sequence defined in `bin/omarchy`:

1. **Direct route attempt** – The `resolve_direct_route` function (lines 98‑104) checks for exact filename matches
2. **Argument passing** – If found, leftover arguments are passed directly to the binary via `exec`
3. **Help interception** – If `--help` or `-h` appears in the remaining arguments, the router loads metadata and displays usage information instead of executing the command
4. **Metadata fallback** – If the fast path fails, the full route table is consulted and the router either executes the correct binary or suggests "did you mean?" alternatives

### Handling Arguments and Help Flags

When a user appends `--help` to any command, the router detects this before execution and renders formatted help text based on the binary's comment header metadata. This ensures consistent documentation without requiring separate man pages.

## Example: Resolving `omarchy theme set foo`

Consider the complete resolution path for the command `omarchy theme set foo`:

- **User input**: Three arguments (`theme`, `set`, `foo`)
- **Fast‑path probe**: The router checks `omarchy-theme-set-foo` (does not exist), then `omarchy-theme-set` (exists at `bin/omarchy-theme-set`)
- **Execution**: The router calls `exec bin/omarchy-theme-set foo`, passing `foo` as an argument to the theme‑setting binary
- **Implementation**: The actual logic for setting themes resides in `bin/omarchy-theme-set`, whose metadata header defines the command summary, argument specifications, and examples

## Summary

- **Filename convention**: Binaries starting with `omarchy-` automatically register routes based on hyphen positions
- **Fast path**: Arguments are joined with hyphens to probe for direct matches before loading metadata
- **Metadata fallback**: If filename probing fails, the router parses comment headers to build a route table supporting aliases and hidden commands
- **Execution model**: Found binaries are executed directly via `exec` with remaining arguments appended
- **Help system**: The router intercepts `--help` flags to display metadata rather than running the command

## Frequently Asked Questions

### How does Omarchy map spaced commands to binaries?

Omarchy replaces spaces with hyphens to construct filenames. The command `omarchy theme set` maps to `bin/omarchy-theme-set` by joining the arguments. The router probes progressively shorter hyphenated combinations until it finds an executable match.

### What happens if no binary matches the command arguments?

If the fast‑path probe fails, the router loads metadata from all `omarchy-*` files, builds a route table, and performs a longest‑prefix lookup. If still unresolved, it displays a "did you mean?" suggestion list based on similar command names.

### How can I add aliases or hide commands in Omarchy?

Add structured comment headers to your `omarchy-*` script within the first 80 lines. According to [`agents/skills/command-metadata.md`](https://github.com/omacom/omarchy/blob/main/agents/skills/command-metadata.md), you can use keys like `omarchy:alias` to register alternate routes or `omarchy:hidden` to exclude the command from help listings.

### Where is the route table stored in Omarchy?

There is no static registry file. The route table is computed dynamically at runtime by scanning the `bin/` directory for `omarchy-*` executables and parsing their metadata headers. This auto‑discovery mechanism eliminates the need to update central configuration when adding new commands.