# How Omarchy Handles Command Aliases and Metadata-Moved Routes: A Deep Dive into the CLI Router

> Discover how Omarchy handles command aliases and metadata-moved routes. Learn about its efficient CLI router design for fast command resolution.

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

---

**Omarchy resolves command aliases and metadata-moved routes by scanning command binaries for specially-formatted metadata comments, storing routes in associative arrays, and registering them in a unified lookup table that maps both primary and fallback routes to the same executable.**

Omarchy is an open-source framework that provides a sophisticated CLI routing system capable of handling multiple entry points for a single command. The routing mechanism lives in `bin/omarchy` and treats every executable prefixed with `omarchy-` as a potential command target. Understanding how Omarchy handles command aliases and metadata-moved routes helps developers create more accessible and discoverable CLI tools within the ecosystem.

## How the Omarchy CLI Router Scans Command Metadata

The routing system begins by discovering available commands through a systematic scan of the filesystem. When the router initializes, it executes `load_commands` to identify all binaries matching the `omarchy-*` pattern and extracts their configuration from the first 80 lines of each file.

### The Metadata Comment Format

Each command binary must include specially-formatted comments that define the command's routing behavior. These comments use the prefix `# omarchy:` followed by key-value pairs.

```bash
#!/usr/bin/env bash

# omarchy:summary=Take a screenshot

# omarchy:aliases=omarchy screenshot

# omarchy:fallback_route=omarchy capture screenshot

```

The parser recognizes three critical metadata keys:

- **`omarchy:summary`** – A human-readable description of the command's function
- **`omarchy:aliases`** – Pipe-separated list of alternative routes (e.g., `omarchy weather|omarchy forecast`)
- **`omarchy:fallback_route`** – A human-friendly path that serves as the metadata-moved route

### Parsing Logic in bin/omarchy

Inside `bin/omarchy`, the `register_command` function processes metadata using pattern matching against `^[[:space:]]*# omarchy:`. The parser extracts keys and values, then populates three associative arrays:

- `COMMAND_ROUTE[key]` – Stores the primary route derived from the filename
- `COMMAND_ALIASES[key]` – Stores the pipe-separated alias list
- `COMMAND_FALLBACK_ROUTE[key]` – Stores the fallback route string

## Registering Primary Routes, Aliases, and Fallback Routes

Once parsed, each route undergoes registration through the `register_route` function, which builds the complete routing table used during command dispatch.

### The register_route Function

For every command, the router establishes distinct entries in the `ROUTE_TO_KEY` associative array. The primary route registers with `is_alias=false`, while each alias registers with `is_alias=true` and sets `ROUTE_IS_ALIAS[route]="true"`. This flagging system allows the router to distinguish canonical routes from shortcuts while ensuring they resolve to the same underlying command key.

When a command specifies `omarchy:fallback_route=omarchy status weather`, the fallback route receives its own entry in `ROUTE_TO_KEY`, enabling users to invoke the command through an intuitive, hierarchical path that differs from the filename-based primary route.

### Collision Detection with ROUTE_COLLISIONS

The router maintains a `ROUTE_COLLISIONS` associative array to track conflicts where two different commands attempt to register identical routes. This prevents ambiguous routing and ensures that each path resolves deterministically to a single executable.

## Dispatching Commands and Resolving Routes

When a user executes `omarchy <route>`, the system translates the provided route into an executable action through a direct lookup mechanism.

### The ROUTE_TO_KEY Lookup Mechanism

The dispatcher consults `ROUTE_TO_KEY[route]` to retrieve the unique command key associated with the requested path. Because both primary routes and aliases populate this same lookup table, the resolution process is identical regardless of which variant the user types. The system then executes the binary associated with the resolved key.

### Handling Metadata-Moved (Fallback) Routes

Fallback routes function as semantic alternatives to the primary filename-based route. For example, a binary named `omarchy-weather` might specify `omarchy:fallback_route=omarchy status weather`, allowing users to discover the command through logical grouping hierarchies. The fallback route receives the same treatment as standard aliases in the `ROUTE_TO_KEY` table, ensuring consistent behavior across all entry points.

## Implementing Custom Commands with Aliases

Developers can create commands that support multiple invocation patterns by including the appropriate metadata headers.

```bash
#!/usr/bin/env bash

# omarchy:summary=Show the current weather

# omarchy:aliases=omarchy weather|omarchy forecast

# omarchy:fallback_route=omarchy status weather

weather() {
    curl -s "https://wttr.in?format=3"
}
weather "$@"

```

With this configuration, users can invoke the command through any of the following equivalent routes:

- `omarchy weather` (primary route based on filename `omarchy-weather`)
- `omarchy forecast` (alias)
- `omarchy status weather` (fallback/metadata-moved route)

## Querying Router Metadata

Omarchy provides built-in introspection capabilities through functions like `show_commands`, `show_commands_json`, and `show_commands_markdown`. These utilities expose the complete routing information, including primary routes, aliases, and fallback routes.

The `commands_json_filter` function constructs a `routes` array containing the primary route, fallback route, and all aliases separated by pipe characters. This ensures that external tooling receives the full routing picture for each command.

```bash
$ omarchy commands --json | jq -r '.commands[] | select(.route=="omarchy weather") | .routes'

# Output:

"omarchy weather|omarchy status weather|omarchy forecast"

```

## Summary

- Omarchy's CLI router resides in `bin/omarchy` and scans `omarchy-*` binaries to build the routing table
- Command metadata is defined within the first 80 lines using `# omarchy:` prefixed comments

- The system uses associative arrays including `COMMAND_ROUTE`, `COMMAND_ALIASES`, and `COMMAND_FALLBACK_ROUTE` to store routing configuration
- All routes—primary, aliases, and fallback—register in `ROUTE_TO_KEY` to ensure consistent dispatch regardless of invocation method
- The `ROUTE_COLLISIONS` array prevents ambiguous routing by detecting duplicate route registrations
- Metadata is exposed through JSON output functions that include all available routes for tooling integration

## Frequently Asked Questions

### What is the difference between an alias and a fallback route in Omarchy?

An **alias** provides alternative short names for invoking a command (e.g., `omarchy screenshot` as an alias for `omarchy capture-screenshot`), while a **fallback route** (metadata-moved route) provides a semantic, human-readable path that often follows a logical hierarchy (e.g., `omarchy capture screenshot`). Both resolve to the same executable, but fallback routes typically indicate a more descriptive or reorganized naming scheme.

### How does Omarchy detect route collisions between commands?

The router stores potential conflicts in the `ROUTE_COLLISIONS` associative array during the registration phase in `register_route`. When two different command binaries attempt to claim the same route string, the collision is recorded, preventing ambiguous routing and ensuring deterministic command execution.

### Where is the command metadata format documented?

The complete specification for `# omarchy:` metadata tags, including `aliases` and `fallback_route`, is documented in [`agents/skills/command-metadata.md`](https://github.com/omacom/omarchy/blob/main/agents/skills/command-metadata.md) within the repository. This file serves as the authoritative reference for developers implementing custom Omarchy commands.

### How can I list all available aliases for a specific command?

Use the JSON output functionality via `omarchy commands --json` and filter for your target command. The `routes` field contains a pipe-separated list of all primary routes, fallback routes, and aliases. Alternatively, the `show_commands` function displays this information in a human-readable table format.