# Omarchy Command Naming Conventions: A Complete Guide to CLI Structure

> Master Omarchy command naming conventions for structured CLI development. Learn the prefix and verb-group structure to build consistent and intuitive commands.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: best-practices
- Published: 2026-08-29

---

**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`](https://github.com/basecamp/omarchy/blob/main/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:

```bash

# 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`](https://github.com/basecamp/omarchy/blob/main/agents/skills/command-metadata.md), while the routing implementation details are documented in [`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md). The actual enforcement logic lives in `bin/omarchy`, which parses command names and maps them to their respective execution handlers.