# How Omarchy CLI Command Groups Are Defined: A Deep Dive into the Architecture > Discover how Omarchy CLI command groups are defined using the GROUP_DESCRIPTIONS associative array in the bin/omarchy script. Learn about automatic command discovery. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: deep-dive - Published: 2026-08-29 --- **Omarchy CLI command groups are defined through an associative array named `GROUP_DESCRIPTIONS` in the `bin/omarchy` wrapper script, which maps group prefixes to human-readable descriptions and automatically discovers commands based on the `omarchy--` filename convention.** The Omarchy desktop environment ships with a sophisticated command-line interface organized into logical command groups. According to the `basecamp/omarchy` source code, these groups are not hardcoded into individual scripts but are instead declared centrally in the main wrapper, enabling dynamic discovery and consistent help generation across the entire toolchain. ## The GROUP_DESCRIPTIONS Associative Array At the heart of Omarchy's command grouping system lies a Bash associative array defined near the top of the core wrapper script. In `bin/omarchy`, the `GROUP_DESCRIPTIONS` array maps each group prefix to its description: ```bash declare -A GROUP_DESCRIPTIONS=( [cmd]="Utility commands" [capture]="Screen‑capture tools" [pkg]="Package‑management helpers" [hw]="Hardware‑detection commands" [refresh]="Configuration‑refresh helpers" # … additional groups … ) ``` This declaration, typically found around lines 80–100 of `bin/omarchy`, serves as the single source of truth for group metadata. When the wrapper executes, it references this array to categorize commands and generate contextual help text. ## Command Naming Convention and File Structure Omarchy enforces a strict filename convention that links individual commands to their respective groups. All executable scripts reside in the `bin/` directory and follow the pattern: ``` bin/omarchy-- ``` For example: - `bin/omarchy-capture-screenshot` belongs to the `capture` group - `bin/omarchy-pkg-add` belongs to the `pkg` group - `bin/omarchy-hw-info` belongs to the `hw` group The wrapper script extracts the group prefix by parsing the filename at the second hyphen position. This convention allows the CLI to organize commands dynamically without maintaining a secondary registry of command-to-group mappings. ## How Command Discovery Works The `bin/omarchy` wrapper implements a two-phase discovery mechanism that leverages both the `GROUP_DESCRIPTIONS` array and the filesystem layout. ### Extracting the Group Prefix When invoked, the wrapper determines the active group by examining the script name: 1. **Input parsing**: If the user runs `omarchy capture`, the wrapper identifies `capture` as the target group 2. **Prefix validation**: It checks if `capture` exists as a key in `GROUP_DESCRIPTIONS` 3. **Command enumeration**: It scans `bin/` for files matching `omarchy-capture-*` ### Generating Help Output The wrapper uses the description from `GROUP_DESCRIPTIONS` to render group-specific help: ```bash # List all commands in the "capture" group $ omarchy capture capture – Screen‑capture tools omarchy-capture-screenshot Capture a full‑screen screenshot omarchy-capture-region Capture a rectangular region omarchy-capture-webcam-list List attached webcams ``` This output is generated dynamically by iterating over matching files in `bin/` and reading the `GROUP_DESCRIPTIONS` entry for the header. ## Adding New Command Groups Extending the CLI with new command groups requires only two steps according to the Omarchy architecture: 1. **Update `GROUP_DESCRIPTIONS`**: Add a new entry to the associative array in `bin/omarchy` with the group prefix and description 2. **Create command scripts**: Add executable files following the `omarchy--` naming pattern to the `bin/` directory The wrapper automatically discovers these new scripts on the next invocation without requiring changes to the dispatch logic. ## Practical Usage Examples The following examples demonstrate how the command group system operates in practice: **Listing all package management commands:** ```bash $ omarchy pkg pkg – Package‑management helpers omarchy-pkg-add Install a package (handles pacman & AUR) omarchy-pkg-drop Remove a package omarchy-pkg-search Search for packages ``` **Viewing hardware detection tools:** ```bash $ omarchy hw hw – Hardware‑detection commands omarchy-hw-info Display system hardware information omarchy-hw-sensors Read sensor data ``` **Accessing utility commands:** ```bash $ omarchy cmd cmd – Utility commands omarchy-cmd-present Presentation mode utilities omarchy-cmd-notify Notification helpers ``` ## Summary - **Centralized definition**: Command groups are defined in the `GROUP_DESCRIPTIONS` associative array within `bin/omarchy` - **Filesystem convention**: Commands follow the strict naming pattern `bin/omarchy--` - **Dynamic discovery**: The wrapper script extracts group prefixes from filenames and cross-references `GROUP_DESCRIPTIONS` to generate help text - **Easy extension**: Adding groups requires only updating the array and creating appropriately named scripts in `bin/` - **Documentation**: Group descriptions are surfaced through `omarchy ` invocations and the top-level help system ## Frequently Asked Questions ### How does the omarchy wrapper know which group a command belongs to? The wrapper extracts the group prefix from the filename of the executed script. When you run `omarchy-capture-screenshot`, the system parses the filename to identify `capture` as the group, then looks up the description in `GROUP_DESCRIPTIONS` to provide context in help output. ### Where is the GROUP_DESCRIPTIONS array defined in the source code? The `GROUP_DESCRIPTIONS` associative array is defined in `bin/omarchy`, typically located near the beginning of the file around lines 80–100. This central location ensures that group metadata is maintained in one place rather than scattered across individual command scripts. ### Can I add a custom command group without modifying the core omarchy script? No, you must update the `GROUP_DESCRIPTIONS` array in `bin/omarchy` to register a new group. While you can create scripts with new prefixes in the `bin/` directory, the wrapper will not recognize them as a formal group or display them in group listings until you add the corresponding entry to the associative array. ### What happens if a command script exists but its group is not in GROUP_DESCRIPTIONS? Commands without a corresponding entry in `GROUP_DESCRIPTIONS` will not appear in group listings or help output. The wrapper relies on this array to validate groups and generate descriptions, so orphaned commands may be accessible by direct invocation but invisible to the discovery system.