Omarchy Command Naming Conventions: A Complete Guide to CLI Structure

All Omarchy commands must begin with the literal prefix omarchy- followed by a dash-separated verb-group that encodes both the command's scope and its specific action.

The Omarchy CLI follows a strict, prefix-based naming scheme designed to create a predictable, discoverable interface. According to the basecamp/omarchy source code, this convention ensures that every public command explicitly identifies its functional group while maintaining a clean top-level namespace.

The Mandatory omarchy- Prefix

Every public command in the Omarchy ecosystem starts with the string omarchy-. This is the sole allowed top-level namespace—no other prefixes are exported or recognized by the CLI router.

In bin/omarchy, the central CLI router parses these command names to determine routing logic and help output. The router maintains a GROUP_DESCRIPTIONS mapping that associates each prefix group with a human-readable heading, driving the organization of the help interface.

Verb-Group Naming Pattern

After the mandatory prefix, command names follow a dash-separated verb-group structure. The first component after omarchy- denotes the functional group, while the remainder describes the specific action or target.

Common Command Groups

The Omarchy CLI organizes commands into semantic groups based on their operational domain:

• omarchy-cmd- — Utility and sanity-check commands that verify external command existence
• omarchy-pkg- — Package management helpers for adding or dropping optional software
• omarchy-hw- — Hardware detection predicates that return exit codes for feature detection
• omarchy-refresh- — Configuration refresh utilities that copy default configs to ~/.config/ with automatic backups
• omarchy-restart- — Service restart commands (e.g., omarchy-restart-shell)
• omarchy-launch- — Application launchers, sometimes with focus handling logic
• omarchy-install- — One-shot installation scripts for optional components (e.g., omarchy-install-service-tailscale)
• omarchy-setup- — Interactive setup wizards (e.g., omarchy-setup-backup)
• omarchy-toggle- — Feature toggles for turning functionality on or off (e.g., omarchy-toggle-idle-screensaver)
• omarchy-theme- — Theme management commands (e.g., omarchy-theme-set)
• omarchy-update- — Update pipeline commands (e.g., omarchy-update-dev)

As documented in agents/skills/command-metadata.md, these prefixes determine how commands are categorized in the help system and validated by the codebase tooling.

Hidden Commands and Internal Utilities

Not all commands appear in the public help listings. Hidden commands are flagged with an inline comment # omarchy:hidden=true immediately following the shebang or function definition.

These commands follow the same omarchy- prefix convention but are omitted from GROUP_DESCRIPTIONS in the router's public interface. They serve as internal plumbing for predicates, low-level IPC helpers, and implementation details that should not clutter the user-facing CLI surface.

The command-metadata skill validates these hidden flags across the codebase, ensuring that internal utilities remain truly internal while maintaining naming consistency with public commands.

How the CLI Router Enforces Conventions

The file bin/omarchy serves as the central router that enforces Omarchy command naming conventions at runtime. When parsing a command name, the router:

1. Verifies the omarchy- prefix
2. Extracts the verb-group component to determine the functional category
3. Looks up the group in GROUP_DESCRIPTIONS to generate contextual help output
4. Routes execution to the appropriate script based on the full command name

If a command belongs to a hidden group (where all members carry the # omarchy:hidden=true metadata), the router excludes that entire group from top-level help output, keeping the interface tidy.

Practical Examples

The following commands demonstrate the Omarchy naming conventions in action:

# Refresh a default config file (copies with backup)

omarchy-refresh-config hypr/hyprland.lua

# Install an optional service

omarchy-install-service-tailscale

# Run an interactive setup wizard

omarchy-setup-backup

# Toggle a system feature on or off

omarchy-toggle-idle-screensaver

# Change the active color theme

omarchy-theme-set tomorrow-night

# Restart a shell component

omarchy-restart-shell

Each example follows the strict omarchy-<group>-<action> pattern, making the command's purpose immediately obvious from its name alone.

Summary

• All public commands must use the omarchy- prefix as enforced by the CLI router in bin/omarchy.

• Commands follow a verb-group pattern where the first component after the prefix indicates the functional group (e.g., refresh, install, toggle).

• Hidden commands use # omarchy:hidden=true comments to exclude internal utilities from public help listings.

• The GROUP_DESCRIPTIONS mapping in the router organizes commands into human-readable categories for the help interface.

• The command-metadata skill validates naming consistency and documentation across the basecamp/omarchy codebase.

Frequently Asked Questions

What happens if a command does not start with omarchy-?

Commands lacking the omarchy- prefix are not recognized by the Omarchy CLI router and will not appear in the public command list or help output. The router in bin/omarchy explicitly filters for this prefix when processing commands, ensuring strict namespace isolation.

How does Omarchy distinguish between public and internal commands?

Internal commands are marked with the comment # omarchy:hidden=true in their source files. The CLI router checks for this metadata and excludes matching commands from GROUP_DESCRIPTIONS and help listings, while the command-metadata skill validates these flags during development.

Can I create custom Omarchy commands with my own verb groups?

While the system allows new scripts in the appropriate directories, they must adhere to the established naming conventions. Custom commands should use the omarchy-<group>-<action> pattern and register their group in GROUP_DESCRIPTIONS within bin/omarchy to appear in help output, or use the hidden flag for private utilities.

Where are the Omarchy command naming rules documented?

The definitive specification resides in agents/skills/command-metadata.md, while the routing implementation details are documented in docs/cli-router.md. The actual enforcement logic lives in bin/omarchy, which parses command names and maps them to their respective execution handlers.

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