How Omarchy Commands with Metadata Aliases Work: Route Registration and Conflict Resolution

Omarchy’s CLI router registers command aliases by scanning the comment headers of bin/omarchy-* executables for the omarchy:alias= metadata key, creating secondary routes that map to the same binary while flagging them as non-primary aliases.

In the basecamp/omarchy repository, command discovery relies on embedded metadata rather than hardcoded routing tables. When an executable in bin/ defines an alias using the omarchy:alias= directive, the router builds an additional route alongside the canonical and filename-based paths. Understanding how Omarchy commands with metadata aliases are handled is essential for building intuitive CLI interfaces that support multiple invocation patterns.

How the CLI Router Discovers Command Metadata

The routing engine builds its dispatch table by analyzing every executable file matching bin/omarchy-*. For each binary, the router reads the comment header—the first approximately 80 lines or until it encounters the first non-comment line—and parses special omarchy: metadata keys.

According to the specification in agents/skills/command-metadata.md, the router extracts directives like omarchy:name=, omarchy:group=, and omarchy:alias= to construct the command's public interface. This metadata-driven approach allows developers to define command behavior without modifying the router's core logic.

Route Registration: Canonical, Filename, and Alias Paths

For every valid command binary, the CLI router registers three distinct route types:

1. Canonical route: Built from the omarchy:group= and omarchy:name= metadata values, formatted as omarchy <group> <name>.
2. Filename route: Derived directly from the binary's filename (omarchy-<group>-<name>), with hyphens converted to spaces.
3. Alias route: Generated from the omarchy:alias= metadata value, pointing to the same executable but flagged as an alias in the routing table.

When you invoke omarchy commands --list, the router displays aliases in a separate "Aliases" column rather than as primary commands, distinguishing them from canonical routes even though they dispatch to the same binary.

Metadata Definition Syntax

Define an alias by adding the omarchy:alias= directive to your executable's comment header:

# File: bin/omarchy-screenshot

# -------------------------------------------------

# # omarchy:name=screenshot

# # omarchy:group=capture

# # omarchy:alias=screen grab

# -------------------------------------------------

This configuration creates three valid invocation paths:

• omarchy capture screenshot (canonical)
• omarchy screenshot (filename-based)
• omarchy screen grab (alias)

Conflict Resolution and Route Priority

The Omarchy router enforces a strict first-come-first-served registration policy. When multiple binaries claim the same route—including aliases—the first registration wins, and subsequent attempts are ignored for that specific route.

Importantly, conflicting binaries remain invokable via their filename routes if those differ from the contested alias or canonical name. The system records all conflicts for later inspection.

Detecting Route Conflicts

Use the built-in diagnostic tool to identify overlapping routes:

$ omarchy commands --check
✖ Conflict: alias "screen grab" already registered by bin/omarchy-screenshot

This command scans the entire routing table and reports collisions between canonical names, filenames, and aliases, helping developers resolve namespace issues before deployment.

Dispatch Flow: Fast-Path vs. Metadata Fallback

The CLI router optimizes common invocations using a two-tier resolution strategy documented in docs/cli-router.md.

First, the router attempts a fast-path filename probe. For example, invoking omarchy theme set triggers an immediate lookup for bin/omarchy-theme-set. If this file exists, the router executes it directly without loading metadata.

Only when the fast-path fails does the router fall back to loading the complete metadata table, including alias definitions. This fallback uses longest-prefix matching against all registered routes—including aliases—to determine the correct binary. This architecture ensures that aliases incur no performance penalty for standard filename-based invocations while remaining available for user-friendly alternative syntax.

Hidden Commands and Alias Visibility

Commands marked with omarchy:hidden=true in their metadata still register aliases and canonical routes; they simply omit themselves from public listings like omarchy commands --list.

This means hidden commands can expose functional aliases that power users discover through documentation or shell completion, while keeping the primary command listing uncluttered. Aliases inherit the hidden status of their parent command in listings, though they remain fully dispatchable.

Summary

• Omarchy scans bin/omarchy-* executables and parses the first ~80 lines of comment headers for omarchy: metadata keys.
• The omarchy:alias= directive creates secondary routes that map to the same binary as canonical routes.
• Three route types exist: canonical (metadata-based), filename (derived from bin/omarchy-<name>), and alias (user-defined).
• First registration wins for conflicts; later collisions are logged and reported via omarchy commands --check.
• The router uses a fast-path filename lookup before falling back to full metadata resolution, ensuring aliases do not slow standard invocations.

Frequently Asked Questions

How do I define an alias for an Omarchy command?

Add the omarchy:alias= directive to your executable's comment header, typically within the first 80 lines. For example, # omarchy:alias=screen grab allows users to invoke your command using omarchy screen grab instead of the canonical route.

What happens if two commands define the same alias?

The first binary scanned by the router claims the alias route; subsequent registrations are ignored for that specific alias. However, conflicting binaries remain accessible via their filename routes. Run omarchy commands --check to detect and view these conflicts.

Do aliases appear in the command listing?

Yes, but they are visually distinguished. When you run omarchy commands --list, aliases appear under a separate "Aliases" column rather than as primary commands, even though they dispatch to the same underlying binary.

Are hidden commands still accessible via aliases?

Absolutely. The omarchy:hidden=true metadata only affects visibility in command listings; it does not prevent route registration. Hidden commands continue to function through their canonical names, filename routes, and any defined aliases.

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