# Canonical vs Filename Routes in Omarchy: CLI Router Deep Dive > Understand canonical vs filename routes in Omarchy CLI. Learn how canonical routes override defaults using metadata for flexible command structures and backward compatibility. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: deep-dive - Published: 2026-08-25 --- **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--` 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`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md), after parsing these metadata directives, the router constructs the canonical route as `omarchy `. 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. ```bash # 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. ```bash # 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`](https://github.com/basecamp/omarchy/blob/main/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=` followed by `# omarchy:name=` (with an empty value) to the executable file. This generates a canonical route of `omarchy ` 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`](https://github.com/basecamp/omarchy/blob/main/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.