# How Command Groups Are Defined in Omarchy: The GROUP_DESCRIPTIONS Registry Explained > Discover how command groups are defined in Omarchy using the GROUP_DESCRIPTIONS registry. Learn how prefixes map to descriptions for clear CLI help output. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: internals - Published: 2026-08-27 --- **Command groups in Omarchy are defined via the `GROUP_DESCRIPTIONS` associative array in `bin/omarchy`, which maps group prefixes like `capture` and `install` to human-readable descriptions that drive the CLI's help output.** Omarchy organizes its user-facing commands into logical groups that share a common prefix, making the toolset intuitive and maintainable. According to the basecamp/omarchy source code, the authoritative registry for these groups lives in a central Bash associative array that powers both command routing and help generation. Understanding how command groups are defined in Omarchy is essential for contributors adding new functionality or customizing the interface. ## The GROUP_DESCRIPTIONS Registry At the heart of Omarchy's command organization is the **`GROUP_DESCRIPTIONS`** associative array defined in **`bin/omarchy`** (lines 27-91). This data structure maps short group identifiers—such as `capture`, `install`, and `theme`—to descriptive strings that appear when users invoke `omarchy ` or request top-level help. ### Registry Structure and Location The dispatcher script `bin/omarchy` serves as the single source of truth for group metadata. When you examine the source, you'll find the `GROUP_DESCRIPTIONS` declaration near the top of the file, establishing a contract between the CLI interface and its various subcommands. Each entry in this array follows the pattern: ```bash GROUP_DESCRIPTIONS[group_key]="Human-readable description of the group" ``` This registry is consulted by the help printer (around line 510) to display a sorted list of available groups when users run `omarchy help` or invoke the binary without arguments. ## File Naming Conventions and Routing Individual commands follow a strict naming convention under the `bin/` directory. Each executable must match the pattern **`bin/omarchy--`**, where `` corresponds to a key registered in the `GROUP_DESCRIPTIONS` array. For example, `omarchy-capture-record` belongs to the `capture` group, while `omarchy-install-package` belongs to the `install` group. When the dispatcher parses arguments, it extracts the group token, looks up its description in the registry, and routes the call to the corresponding script. ## Help Generation and User Experience The `GROUP_DESCRIPTIONS` array directly powers the help system. As implemented in basecamp/omarchy, the help printer iterates through this associative array around line 510 in `bin/omarchy` to generate the categorized command listing. This ensures that users see consistent, up-to-date descriptions for every command group without manual updates to the help text logic. ## Maintaining the Registry The **[`AGENTS.md`](https://github.com/basecamp/omarchy/blob/main/AGENTS.md)** documentation (line 38) explicitly requires contributors to keep the `GROUP_DESCRIPTIONS` array up-to-date whenever a new command prefix is added. This policy ensures the top-level help output remains accurate and that new functionality is immediately discoverable by users. ## Hidden Commands Not all commands appear in help listings. Developers can mark scripts as hidden by including the comment **`# omarchy:hidden=true`** in the source file. These commands remain routable by the dispatcher but are omitted from the `GROUP_DESCRIPTIONS`-driven help display, allowing for experimental or administrative functions that shouldn't clutter the standard interface. ## Adding a New Command Group To define a new command group in Omarchy, follow this implementation pattern: ```bash # Step 1: Create the command script following the naming convention # File: bin/omarchy-newgroup-action #!/usr/bin/env bash # ...implementation details... # Step 2: Register the group in bin/omarchy (lines 27-91) # Add to the GROUP_DESCRIPTIONS associative array: GROUP_DESCRIPTIONS[newgroup]="Description of the new group functions" # Step 3: Verify via help output omarchy help ``` Key files involved in this process include: - **`bin/omarchy`** — Central dispatcher that defines `GROUP_DESCRIPTIONS` and routes commands - **[`AGENTS.md`](https://github.com/basecamp/omarchy/blob/main/AGENTS.md)** — Developer guidance requiring registry maintenance - **`bin/omarchy--*`** — Individual command scripts belonging to specific groups ## Summary - The **`GROUP_DESCRIPTIONS`** associative array in **`bin/omarchy`** serves as the authoritative registry for all command groups in the basecamp/omarchy repository. - Group definitions appear at lines 27-91 and drive help output generation around line 510. - Command scripts must follow the **`bin/omarchy--`** naming pattern to be properly routed. - The **[`AGENTS.md`](https://github.com/basecamp/omarchy/blob/main/AGENTS.md)** file at line 38 requires updates to this registry whenever introducing new group prefixes. - Hidden commands use **`# omarchy:hidden=true`** to exclude themselves from help listings while remaining callable. ## Frequently Asked Questions ### What file defines command groups in Omarchy? Command groups are defined in the **`bin/omarchy`** dispatcher script through the **`GROUP_DESCRIPTIONS`** associative array located at lines 27-91. This Bash data structure maps group identifiers like `capture` and `install` to their human-readable descriptions, which the help printer references around line 510. ### How do I add a new command group to Omarchy? Create a script named **`bin/omarchy--`** for your command, then add an entry to the `GROUP_DESCRIPTIONS` array in `bin/omarchy` following the existing pattern at lines 27-91. The [`AGENTS.md`](https://github.com/basecamp/omarchy/blob/main/AGENTS.md) documentation at line 38 mandates this registry update to ensure the new group appears in the top-level help output. ### Why isn't my new command showing up in the help output? Verify that you have added the group identifier to the **`GROUP_DESCRIPTIONS`** array in `bin/omarchy` and confirm the script filename follows the **`omarchy--`** convention. If the script contains **`# omarchy:hidden=true`**, it will be intentionally excluded from help listings while remaining fully functional. ### Can I hide a command from the group listings while keeping it functional? Yes. Add the comment **`# omarchy:hidden=true`** to the command script's source code. The dispatcher will still route calls to this script, but the help printer (around line 510) will exclude it from the visible group listings derived from `GROUP_DESCRIPTIONS`.