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

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.

#!/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.

#!/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.

$ 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}