Canonical vs Filename Routes in Omarchy: CLI Router Deep Dive

Canonical routes are derived from metadata comments that override default filename routes, allowing developers to preserve hyphens, restructure command hierarchies, or create root-level group commands while maintaining backward-compatible filename-based paths.

Omarchy’s CLI router automatically exposes every executable script under bin/omarchy-* as a terminal command. Each binary registers two distinct route types—the filename route and the canonical route—that determine how users invoke functionality, with the canonical route providing a polished interface over the filesystem-based default.

Understanding Filename Routes

The filename route serves as the automatic fallback mechanism when no metadata overrides are present. The router derives this path directly from the executable’s filename using a deterministic parsing algorithm implemented in bin/omarchy.

For any script named omarchy-<group>-<name> stored in the bin/ directory, the router splits the filename at the first hyphen to determine the group, then converts all remaining hyphens into spaces to form the name. For example, the file bin/omarchy-theme-set automatically generates the filename route omarchy theme set by mapping theme as the group and transforming the remaining set into the command name.

Understanding Canonical Routes

The canonical route originates from metadata comments embedded within the executable file itself, specifically lines containing # omarchy:group=… and # omarchy:name=…. These directives allow developers to explicitly define how the command appears to users, independent of the actual filename.

According to the routing logic documented in docs/cli-router.md, after parsing these metadata directives, the router constructs the canonical route as omarchy <group> <name>. This mechanism enables significant flexibility: developers can rename groups, preserve hyphens within command names, or eliminate the name entirely to create group-root commands.

Key Differences Between Route Types

While both routes always execute the same underlying binary, they differ in derivation, flexibility, and user experience:

• Source of truth: Filename routes derive strictly from the filesystem (bin/omarchy-* filenames), while canonical routes derive from inline metadata comments parsed by the router.

• Hyphen handling: Filename routes convert all hyphens to spaces, potentially breaking compound terms like "xbox-cloud" into separate words. Canonical routes preserve exact spacing as defined in the # omarchy:name= metadata.

• Structural flexibility: Canonical routes support empty name values to create root-level group commands, a pattern impossible to achieve through filenames alone.

• Registration behavior: Both routes are always registered simultaneously, ensuring backward compatibility even when metadata overrides the default structure.

Practical Route Divergence Examples

The distinction becomes critical when metadata intentionally overrides the default filename parsing to improve the user interface.

Preserving Hyphens in Command Names

Consider bin/omarchy-install-gaming-xbox-cloud. Without metadata, the filename route becomes omarchy install gaming xbox cloud, splitting "xbox-cloud" incorrectly. By adding the metadata comment # omarchy:name=gaming xbox-cloud, the canonical route becomes omarchy install gaming xbox-cloud, preserving the intended hyphenation while the filename route remains unchanged as a secondary alias.

# Filename route (default parsing)

omarchy install gaming xbox cloud

# Canonical route (metadata override)

omarchy install gaming xbox-cloud

Creating Root-Level Group Commands

The file bin/omarchy-menu-share normally generates the filename route omarchy menu share. By specifying # omarchy:group=share and # omarchy:name= (empty value) within the script, the canonical route becomes simply omarchy share, effectively making the command the root of the share group while maintaining the filename route for backward compatibility.

# Canonical route (empty name metadata)

omarchy share

# Filename route (original file-based path)

omarchy menu share

Route Registration and Collision Handling

The entry point script bin/omarchy implements the routing logic that registers both routes simultaneously for every executable. The system builds the GROUP_DESCRIPTIONS table to organize commands and handles potential conflicts through a first-registration-wins policy.

If two binaries claim the identical route—whether through filename convergence or metadata conflicts—the router retains the first discovered route and reports the collision. Developers can detect these conflicts by running omarchy commands --check, which validates the integrity of the command namespace against the metadata specifications defined in agents/skills/command-metadata.md.

Summary

• Filename routes provide automatic, metadata-free routing based strictly on bin/omarchy-* filenames, converting hyphens to spaces.

• Canonical routes offer polished, user-facing command paths defined via # omarchy:group= and # omarchy:name= metadata comments.

• Both routes coexist for every command, ensuring backward compatibility while allowing interface refinement.

• Metadata can preserve hyphens, restructure command hierarchies, or create root-level group commands.

• The router detects collisions via omarchy commands --check and prioritizes first-registered routes when conflicts occur.

Frequently Asked Questions

What happens when canonical and filename routes conflict?

When two different binaries generate identical routes—either through metadata convergence or filename patterns—the Omarchy router applies a first-registration-wins policy. The conflict is flagged when running omarchy commands --check, allowing developers to resolve namespace collisions before deployment.

How do I make a command the root of its group?

Add the metadata comments # omarchy:group=<yourgroup> followed by # omarchy:name= (with an empty value) to the executable file. This generates a canonical route of omarchy <yourgroup> while preserving the filename route as an accessible alias.

Where does Omarchy store route metadata?

Route metadata exists as inline comments within the executable scripts themselves, using the format # omarchy:key=value. The parser extracts these directives during command discovery, as detailed in agents/skills/command-metadata.md and implemented in the main bin/omarchy dispatcher.

How can I check for route collisions in my Omarchy installation?

Execute omarchy commands --check from the terminal. This command validates all registered canonical and filename routes against the current set of executables in bin/omarchy-*, reporting any overlapping paths or metadata inconsistencies.

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