# Understanding the Naming Convention for Omarchy CLI Binaries > Discover the Omarchy CLI binary naming convention: omarchy--. Understand how each segment defines the command structure for easy use. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: deep-dive - Published: 2026-08-25 --- **Omarchy CLI binaries follow a strict hyphen-delimited pattern: `omarchy--`, where every executable in the `bin/` directory starts with the `omarchy-` prefix, uses the first segment as the command group, and treats subsequent segments as the command name.** The Omarchy CLI architecture in the `basecamp/omarchy` repository implements command routing through individual executable files rather than traditional subcommands. Each binary in the `bin/` directory follows a predictable naming convention that determines how users invoke commands via the main router script. Understanding this pattern is essential for developing new commands or debugging dispatch behavior in `bin/omarchy`. ## The `omarchy--` Pattern All CLI binaries reside in the repository's `bin/` directory and follow a rigid three-part naming convention: - **Prefix** – Every binary must start with the literal string `omarchy-`. - **Group** – The first component after the prefix defines the command *group*. - **Name** – Remaining components (if any) form the specific command *name*. This creates filenames like `omarchy-theme-set`, where `theme` is the group and `set` is the command name. ### Single-Segment Commands When a command comprises only the group segment with no additional name components, the binary name consists solely of `omarchy-`. According to the router logic in `bin/omarchy`, these single-segment commands act as the root command for their respective groups. ```bash # Single-segment command (group: "update") $ omarchy update # Internally executes: exec bin/omarchy-update ``` ### Root Commands with Empty Names To designate a binary as the root command of its group while maintaining the hyphenated structure, Omarchy supports an empty name segment expressed as `omarchy--`. The trailing hyphen indicates that this binary handles invocations where only the group is specified. For example, `omarchy-menu-share` becomes the root of the `share` group. ```bash # Root of the "share" group $ omarchy menu share # Executes: exec bin/omarchy-menu-share ``` ## Command Dispatch and Space-to-Hyphen Mapping The main router script, located at `bin/omarchy`, converts user input into filesystem paths by replacing spaces with hyphens. When a user executes a spaced command, the router prepends `omarchy-` to the hyphen-joined arguments and attempts to execute the resulting filename from the `bin/` directory. ```bash # User input with spaces $ omarchy theme set solarized # Router converts to: exec bin/omarchy-theme-set solarized # Hardware command example $ omarchy hw asus-rog # Maps to: exec bin/omarchy-hw-asus-rog ``` The filename serves as the **canonical route** unless metadata within the binary overrides the display name or aliases. ## Metadata Overrides and Canonical Routes While the filename determines the default routing path, binaries can override their invocation patterns through embedded metadata. As documented in [`agents/skills/command-metadata.md`](https://github.com/basecamp/omarchy/blob/main/agents/skills/command-metadata.md), special comments within the binary can define a canonical route that differs from the hyphenated filename. For example, a binary named `bin/omarchy-install-gaming-xbox-cloud` might contain metadata specifying `omarchy:name=gaming xbox-cloud`. This allows the command to be invoked using spaces in the name portion while maintaining the strict hyphenated filename: ```bash # Canonical route (from metadata) $ omarchy install gaming xbox-cloud # Filename route (default) $ omarchy install gaming xbox cloud ``` Hidden commands and aliases follow the same naming convention but are flagged in their metadata to control visibility in command listings generated by the router. ## Key Source Files The naming convention is implemented and documented in the following locations: - **`bin/omarchy`** – The main router script responsible for discovering binaries and dispatching commands based on the naming pattern. - **[`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md)** – Design documentation explaining the relationship between filenames and CLI routes. - **[`agents/skills/command-metadata.md`](https://github.com/basecamp/omarchy/blob/main/agents/skills/command-metadata.md)** – Reference for metadata keys that modify routing behavior, names, and visibility flags. ## Summary - Omarchy CLI binaries use the pattern **`omarchy--`** stored in the repository's `bin/` directory. - The **prefix** `omarchy-` is mandatory for all command executables. - The **group** component maps to the first argument, while the **name** component maps to subsequent arguments. - **Empty names** (indicated by a trailing hyphen) designate root commands for their groups. - The router in `bin/omarchy` converts spaces to hyphens to locate the correct binary. - **Metadata overrides** in individual binaries can define canonical routes without renaming files. ## Frequently Asked Questions ### What is the difference between `omarchy-update` and `omarchy-menu-share`? According to the CLI router documentation in [`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md), `omarchy-update` represents a single-segment command where the group is `update` and it functions as the root command of that group. In contrast, `omarchy-menu-share` uses an empty name segment to become the root of the `share` group under the `menu` namespace. The former handles `omarchy update`, while the latter handles `omarchy menu share`. ### Can I use underscores instead of hyphens in Omarchy binary names? No. The naming convention strictly requires hyphens as delimiters. The router splits user input on spaces and joins them with hyphens to construct the filename. Using underscores would break the dispatch mechanism, as the router specifically looks for files matching the `omarchy--` pattern with hyphen separators. ### How do I create a hidden command that doesn't appear in help listings? Create the binary following the standard `omarchy--` pattern, then add the appropriate metadata flag inside the executable file. According to [`agents/skills/command-metadata.md`](https://github.com/basecamp/omarchy/blob/main/agents/skills/command-metadata.md), hidden commands keep the same naming rule but are flagged with metadata such as `omarchy:hidden=true`. The router checks these flags when generating command listings. ### What is the maximum depth for command groups and subcommands? The convention supports arbitrary nesting through additional hyphen segments. For example, `bin/omarchy-hw-laptop-display-brightness` would handle the command `omarchy hw laptop display brightness`. Each additional word in the user command maps to an additional hyphen-delimited segment in the filename, allowing for deeply nested command hierarchies while maintaining the simple space-to-hyphen translation logic in `bin/omarchy`.