Understanding Omarchy Command Group Prefixes and Their Purposes

TLDR: Omarchy organizes its CLI into twelve user-facing command group prefixes—including cmd-, capture-, pkg-, and theme-—defined in the GROUP_DESCRIPTIONS table located in bin/omarchy, alongside two hidden internal prefixes (apply- and provision-) that handle plumbing without appearing in top-level menus.

The basecamp/omarchy repository structures its command-line interface using semantic command group prefixes that categorize operations by function. These prefixes are authoritatively defined in the GROUP_DESCRIPTIONS associative array within the main bin/omarchy executable, determining how commands are discovered, documented, and routed throughout the system.

Architecture of Omarchy Command Groups

Each Omarchy command follows the naming convention omarchy-<prefix>-<verb>, where the prefix determines the command's functional category. The GROUP_DESCRIPTIONS table in bin/omarchy maps these prefixes to human-readable descriptions that drive the generated help output and CLI organization [AGENTS.md – line 38]. This design allows the CLI router to automatically categorize commands without hardcoding logic for each individual executable [docs/cli‑router.md – line 101‑106].

User-Facing Command Group Prefixes

The following prefixes appear in the public GROUP_DESCRIPTIONS list and represent the primary interfaces for Omarchy users.

System Utilities and Hardware Detection

Commands in this category manage low-level system checks and hardware identification.

• cmd-: Miscellaneous utility commands that verify command existence or perform small checks. Example: omarchy-cmd-missing checks if a specified binary is absent from the system.
• hw-: Hardware-detection utilities for specific device families. Example: omarchy-hw-asus-rog detects ASUS ROG hardware configurations.
• restart-: Service or component restart operations. Example: omarchy-restart-omarchy reloads the Omarchy daemon.

Software and Package Management

These prefixes handle installation, removal, and maintenance of system packages and optional software.

• pkg-: Core package-management helpers for adding or removing software. Example: omarchy-pkg-add vim installs the specified package.
• install-: One-shot installation steps for optional services or complex software stacks. Example: omarchy-install-service-sunshine sets up the Sunshine remote-desktop service.
• update-: System maintenance and upgrade operations. Example: omarchy-update-system-pkgs safely updates system packages while pruning unnecessary dependencies.

Configuration and Environment Setup

These groups manage user configuration files, themes, and feature toggles.

• refresh-: Copies default configuration files into the user's ~/.config/ directory without overwriting customizations. Example: omarchy-refresh-config hypr/hyprland.lua.
• setup-: Interactive setup wizards that can be re-run to reconfigure security or system settings. Example: omarchy-setup-security-sshd runs the SSH security configuration wizard.
• toggle-: Binary state changes for hardware features or system behaviors. Examples: omarchy-toggle-touchscreen on enables the touchscreen, while omarchy-toggle-nightlight off disables the night-light filter.
• theme-: Theme lifecycle management including installation, switching, and asset refresh. Example: omarchy-theme-switcher solarized applies the Solarized color scheme.

Media and Application Launchers

These prefixes handle visual capture and application launching.

• capture-: Screenshot and screen recording utilities. Examples: omarchy-capture-screenshot and omarchy-capture-record.
• launch-: Application launchers that open specific programs or URLs. Example: omarchy-launch-browser opens the default web browser.

Hidden Internal Prefixes

Two prefixes are deliberately excluded from GROUP_DESCRIPTIONS and user-facing menus because they serve internal plumbing functions [AGENTS.md – line 58]:

• apply-: Handles configuration application and state transitions.
• provision-: Manages system provisioning and initialization tasks.

These commands still route through the standard CLI dispatcher but remain hidden from the top-level help output generated by bin/omarchy [docs/cli‑router.md – line 101].

Practical Command Examples

The following demonstrations illustrate the consistent naming pattern across all Omarchy command groups:

# Utility and hardware checks

omarchy-cmd-present git
omarchy-hw-asus-rog

# Package operations

omarchy-pkg-add neovim
omarchy-pkg-drop neovim

# Configuration and themes

omarchy-refresh-config waybar/config
omarchy-theme-refresh
omarchy-toggle-screensaver off

# System maintenance

omarchy-update-available
omarchy-restart-omarchy

Command Discovery and File Layout

Omarchy discovers available commands by scanning for executables matching the omarchy-<group>-<verb> pattern in the system path. The GROUP_DESCRIPTIONS table in bin/omarchy provides the categorical metadata that groups these commands in help documentation [docs/file‑layout.md – line 354]. When developing new commands, maintainers must update GROUP_DESCRIPTIONS to ensure proper categorization, as noted in the repository's agent guidelines [AGENTS.md – line 38].

Summary

• Omarchy uses command group prefixes to organize CLI tools into logical functional categories.
• The GROUP_DESCRIPTIONS table in bin/omarchy defines twelve user-facing prefixes including cmd-, pkg-, theme-, and update-.
• Two internal prefixes—apply- and provision-—remain hidden from user menus but still route through the CLI dispatcher.
• All commands follow the omarchy-<prefix>-<verb> naming convention for automatic discovery and categorization.
• Prefixes determine how commands appear in help output and documentation generated by the CLI router.

Frequently Asked Questions

What are command group prefixes in Omarchy?

Command group prefixes are semantic identifiers that categorize Omarchy CLI commands by function. Each prefix—such as pkg- for package management or theme- for visual customization—appears at the start of the command name (e.g., omarchy-pkg-add) and determines how the CLI router organizes the command in help menus.

Where are the command group prefixes defined in the source code?

The authoritative list resides in the GROUP_DESCRIPTIONS associative array within bin/omarchy, which maps each prefix to a human-readable description [AGENTS.md – line 38]. This table drives the categorization logic referenced in docs/cli-router.md and docs/file-layout.md.

Why are some command prefixes hidden from the top-level menu?

The apply- and provision- prefixes are intentionally omitted from GROUP_DESCRIPTIONS because they handle internal plumbing and system initialization tasks that users typically do not invoke directly [AGENTS.md – line 58]. These commands remain functional but do not appear in standard help output.

How do I create a new command within an existing group?

Create an executable script named omarchy-<prefix>-<verb> following the existing naming convention in bin/omarchy. Ensure the prefix is already defined in GROUP_DESCRIPTIONS so the CLI router correctly categorizes your command in the generated documentation [docs/file‑layout.md – line 354].

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