Understanding the Naming Convention for Omarchy CLI Binaries

Omarchy CLI binaries follow a strict hyphen-delimited pattern: omarchy-<group>-<name>, 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-<group>-<name> 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-<group>. According to the router logic in bin/omarchy, these single-segment commands act as the root command for their respective groups.

# 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-<group>-. 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.

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

# 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, 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:

# 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 – Design documentation explaining the relationship between filenames and CLI routes.
• 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-<group>-<name> 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, 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-<group>-<name> 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-<group>-<name> pattern, then add the appropriate metadata flag inside the executable file. According to 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.

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