# How Omarchy CLI Commands Are Organized into Groups: The Complete Guide > Learn how Omarchy CLI commands organize into groups using a deterministic naming convention like omarchy--. Discover the complete guide to Omarchy command organization. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: how-to-guide - Published: 2026-08-21 --- **Omarchy CLI commands are organized into logical groups using a deterministic naming convention where each executable script follows the pattern `omarchy--`, with the central router managing group metadata and dispatching via the `GROUP_DESCRIPTIONS` associative array.** The Omarchy command-line interface implements a structured group-based architecture that simplifies system management through intuitive categorical organization. Understanding how Omarchy CLI commands are organized into groups reveals the deterministic routing mechanism that maps user inputs to specific Bash scripts. This guide examines the source code in `basecamp/omarchy` to explain the file naming conventions, routing logic, and group classification system. ## The File Naming Convention That Defines Command Groups Every user-facing Omarchy CLI command exists as a separate Bash script within the `bin/` directory. The **file naming convention** strictly follows the pattern `omarchy--`, where the group represents a functional category and the verb specifies the action. For example, the command `omarchy toggle nightlight` corresponds directly to the script `bin/omarchy-toggle-nightlight`. This places the command within the **toggle** group, which handles feature toggles throughout the system. Similarly, `bin/omarchy-theme-list` belongs to the **theme** group and implements the list verb for theme management. This naming convention creates an implicit mapping between the command syntax and the filesystem. When users type `omarchy `, the system locates the exact script by concatenating the components with hyphens. ## How the Central Router Manages Group Descriptions The `bin/omarchy` script serves as the central router that coordinates all Omarchy CLI commands. This script maintains the master list of valid groups and their descriptions through the associative array `GROUP_DESCRIPTIONS` defined at line 27. ### The GROUP_DESCRIPTIONS Associative Array The `GROUP_DESCRIPTIONS` array maps each group name to a human-readable description that appears in help text. According to the source code spanning lines 29-92, this array enumerates all functional categories including hardware control (`hw`), package management (`pkg`), theme handling (`theme`), system updates (`update`), and toggles (`toggle`). Each entry uses the syntax `GROUP_DESCRIPTIONS[group_name]="Description text"` to define the group's purpose. When users invoke the help system or list available commands, the router references this array to display contextual information about what each group controls. ### Routing Logic and Command Dispatch The routing mechanism implemented at line 509 in `bin/omarchy` extracts the group identifier from the command arguments. The router validates the group against `GROUP_DESCRIPTIONS`, then constructs the target script name by combining `omarchy`, the group, and the verb with hyphen separators. If the user executes `omarchy update status`, the router verifies that `update` exists as a valid group key, then dispatches execution to `bin/omarchy-update-status`. This deterministic approach ensures that every valid command maps to exactly one executable script. ## Practical Examples of Group-Based Command Usage The following examples demonstrate how Omarchy CLI commands map to specific groups and scripts: ```bash # Toggle the screen night-light on/off (group: toggle) omarchy toggle nightlight # List all installed themes (group: theme) omarchy theme list # Install a missing optional package (group: install) omarchy install pkg # Show a summary of the update status (group: update) omarchy update status # Refresh a user configuration file (group: refresh) omarchy refresh config hypr/hyprland.lua ``` Each command above resolves to a specific script in the `bin/` directory following the `omarchy--` pattern. The **toggle** group manages binary feature states, while the **theme** group handles visual customization. Package operations reside in **install** and **pkg** groups, and system maintenance commands populate the **update** and **refresh** groups. ## Key Source Files Supporting the Group Architecture Several critical files define and document the Omarchy CLI command group system: - **`bin/omarchy`** – The central router script containing the `GROUP_DESCRIPTIONS` associative array (line 27) and the routing dispatch logic (line 509). - **[`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md)** – Documentation explaining how the CLI routing mechanism processes group inputs and displays help text for command groups. - **[`docs/file-layout.md`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md)** – Specification of the file naming conventions, confirming that user-facing commands follow the `omarchy--` pattern. - **`bin/omarchy--`** – Individual command scripts implementing concrete behavior for each verb within their respective groups. ## Summary Omarchy CLI commands are organized into groups through a deterministic filesystem-based architecture: - **Script naming** follows the strict pattern `omarchy--` in the `bin/` directory. - **Group metadata** is centralized in the `GROUP_DESCRIPTIONS` associative array within `bin/omarchy`. - **Routing logic** at line 509 validates groups and dispatches to the appropriate script. - **Functional coverage** includes groups for hardware (`hw`), packages (`pkg`, `install`), themes (`theme`), updates (`update`), toggles (`toggle`), and configuration (`refresh`). ## Frequently Asked Questions ### How does Omarchy determine which group a command belongs to? Omarchy extracts the group identifier from the second positional argument in the command invocation. The router script `bin/omarchy` validates this identifier against the `GROUP_DESCRIPTIONS` associative array, then constructs the target script path by combining `omarchy`, the group name, and the verb with hyphens. ### Can I create custom command groups in Omarchy? Yes, custom groups require creating a new entry in the `GROUP_DESCRIPTIONS` array inside `bin/omarchy` and placing executable scripts named `omarchy--` in the `bin/` directory. The router automatically recognizes new groups added to the associative array at lines 29-92. ### Where are the human-readable descriptions for command groups defined? The `GROUP_DESCRIPTIONS` associative array in `bin/omarchy` (starting at line 27) contains all group descriptions. This array maps group names like `toggle`, `theme`, and `update` to descriptive strings that appear in help output when users request assistance with specific command categories. ### What happens if I run an Omarchy command with an invalid group name? The router checks the requested group against the `GROUP_DESCRIPTIONS` array. If the group does not exist in this associative array, the routing logic at line 509 fails validation and displays an error message or help text rather than attempting to execute a non-existent script.