# Understanding Omarchy Command Group Prefixes and Their Purposes > Explore Omarchy command group prefixes like cmd, capture, pkg, and theme. Understand their purposes and how they organize the Omarchy CLI for efficient use. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: deep-dive - Published: 2026-08-24 --- **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--`, 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]](https://github.com/basecamp/omarchy/blob/quattro/AGENTS.md#L38). This design allows the CLI router to automatically categorize commands without hardcoding logic for each individual executable [[docs/cli‑router.md – line 101‑106]](https://github.com/basecamp/omarchy/blob/quattro/docs/cli-router.md#L101). ## 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]](https://github.com/basecamp/omarchy/blob/quattro/AGENTS.md#L58): - **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]](https://github.com/basecamp/omarchy/blob/quattro/docs/cli-router.md#L101). ## Practical Command Examples The following demonstrations illustrate the consistent naming pattern across all Omarchy command groups: ```bash # 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--` 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]](https://github.com/basecamp/omarchy/blob/quattro/docs/file-layout.md#L354). 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]](https://github.com/basecamp/omarchy/blob/quattro/AGENTS.md#L38). ## 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--` 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]](https://github.com/basecamp/omarchy/blob/quattro/AGENTS.md#L38). This table drives the categorization logic referenced in [`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md) and [`docs/file-layout.md`](https://github.com/basecamp/omarchy/blob/main/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]](https://github.com/basecamp/omarchy/blob/quattro/AGENTS.md#L58). 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--` 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]](https://github.com/basecamp/omarchy/blob/quattro/docs/file-layout.md#L354).