# GROUP_DESCRIPTIONS in Omarchy: How Command Group Metadata Shapes CLI Output

> Learn how GROUP_DESCRIPTIONS in Omarchy's bin/omarchy Bash script create categorized CLI help listings using command group metadata for enhanced user experience.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: internals
- Published: 2026-09-11

---

**GROUP_DESCRIPTIONS is a Bash associative array defined in `bin/omarchy` that maps command group identifiers to human-readable descriptions, automatically driving the categorized help listings in the Omarchy CLI.**

The `GROUP_DESCRIPTIONS` associative array serves as the single source of truth for command group metadata in the Omarchy CLI framework. Defined in the core router script of the omacom/omarchy repository, this data structure determines how command categories appear to users when they run `omarchy help` or invoke specific tool groups. Understanding this mapping mechanism is essential for developers extending the CLI with new functionality.

## What Is GROUP_DESCRIPTIONS?

`GROUP_DESCRIPTIONS` is declared as an associative array in the main router script at the beginning of `bin/omarchy` (lines 27–97). Each key represents a command group—the word that follows the `omarchy-` prefix in script filenames—while each value provides a concise, user-facing description:

```bash
declare -A GROUP_DESCRIPTIONS
GROUP_DESCRIPTIONS[agent]="AI coding agent usage data"
GROUP_DESCRIPTIONS[ascii]="Text drawn as ASCII art"
GROUP_DESCRIPTIONS[audio]="Audio input and output controls"

# … (continues for every user-facing group) …

GROUP_DESCRIPTIONS[windows]="Windows VM management"

```

This centralized lookup table eliminates hardcoded display strings throughout the codebase. When the development team adds a new command prefix, they register it here to ensure consistent presentation across all user interfaces.

## How GROUP_DESCRIPTIONS Influences Omarchy Command Listings

The router leverages this array in three distinct phases when generating command listings or handling group-specific invocations:

**1. Alphabetically sorting available groups**
The router collects all defined groups by iterating over the array keys, ensuring deterministic output ordering (lines 512–514):

```bash
printf '%s\n' "${!GROUP_DESCRIPTIONS[@]}" | sort | while IFS= read -r sorted_group; do …

```

**2. Retrieving the display title**
When rendering help for a specific group, the router extracts the description to use as a heading (line 804):

```bash
local title="${GROUP_DESCRIPTIONS[$group]}"

```

**3. Discovering and listing verbs**
After establishing the group title, the router searches for executable scripts matching the pattern `bin/omarchy-$group-*`. Each discovered verb is listed beneath its corresponding group header, creating a hierarchical help output without requiring manual updates to the display logic.

Consequently, any modification to `GROUP_DESCRIPTIONS` instantly propagates to the user-facing command list without additional code changes.

## Practical Implementation Examples

### Adding a New Command Group

To create a `cloud` group for cloud-service utilities:

1. **Register the group in `bin/omarchy`:**

```bash
GROUP_DESCRIPTIONS[cloud]="Cloud service helpers"

```

2. **Create verb scripts** following the filename convention:

- `bin/omarchy-cloud-sync`
- `bin/omarchy-cloud-status`

Include the standard metadata marker in each script: `# omarchy:summary=Description here`.

3. **Verify the integration:**

```bash
$ omarchy help
...
cloud           Cloud service helpers
  sync           Sync files to the configured cloud provider
  status         Show current cloud connection status
...

```

The `cloud` header appears automatically because the router reads from `GROUP_DESCRIPTIONS`, while the verbs are discovered dynamically from the filesystem.

### Updating an Existing Group Description

If a group name requires clarification, edit the array entry directly:

```bash
GROUP_DESCRIPTIONS[weather]="Weather information & forecasts"

```

The next invocation of `omarchy weather` or `omarchy help` reflects the new description immediately.

## Key Files and Maintenance Guidelines

According to the Omarchy source code, three primary locations document and enforce the `GROUP_DESCRIPTIONS` contract:

- **`bin/omarchy`** — Contains the array definition (lines 27–97) and the routing logic that queries it (lines 512–514, 804).
- **[`docs/cli-router.md`](https://github.com/omacom/omarchy/blob/main/docs/cli-router.md)** — Explains that the table "also titles each group" (lines 101–106), providing architectural context for contributors.
- **[`AGENTS.md`](https://github.com/omacom/omarchy/blob/main/AGENTS.md)** — Reminds developers to keep `GROUP_DESCRIPTIONS` synchronized when adding new command prefixes (line 38).

This distributed documentation ensures that the metadata table remains accurate as the CLI surface expands.

## Summary

- **GROUP_DESCRIPTIONS** is a Bash associative array in `bin/omarchy` that maps group identifiers to display descriptions.
- The array drives automatic generation of categorized help listings by providing human-readable headers for each command group.
- Adding a new group requires only a single array entry and adherence to the `bin/omarchy-$group-*` filename convention.
- Updates to descriptions take effect immediately across all CLI outputs without modifying display logic.
- Maintenance guidelines in [`docs/cli-router.md`](https://github.com/omacom/omarchy/blob/main/docs/cli-router.md) and [`AGENTS.md`](https://github.com/omacom/omarchy/blob/main/AGENTS.md) ensure long-term consistency.

## Frequently Asked Questions

### Where is GROUP_DESCRIPTIONS defined in the Omarchy codebase?

The array is defined in `bin/omarchy` between lines 27 and 97. This location serves as the central registry for all command group metadata, with each entry following the syntax `GROUP_DESCRIPTIONS[key]="Description"`.

### Do I need to modify GROUP_DESCRIPTIONS when adding new commands?

Yes. When creating a new command group (a new prefix after `omarchy-`), you must add a corresponding entry to `GROUP_DESCRIPTIONS` in `bin/omarchy`. This registration ensures the group appears in `omarchy help` output with a proper descriptive header. Individual verbs within an existing group do not require array modifications.

### How does the router use GROUP_DESCRIPTIONS to generate output?

The router uses the array in two critical paths: first, it sorts the keys alphabetically to determine section ordering (lines 512–514); second, it retrieves the description via `${GROUP_DESCRIPTIONS[$group]}` to print as the section title (line 804). This separation of identifier and display text keeps the CLI presentation consistent.

### What filename convention works with GROUP_DESCRIPTIONS?

The router expects verb scripts to follow the pattern `bin/omarchy-$group-*`, where `$group` matches a key in `GROUP_DESCRIPTIONS`. For example, a group registered as `GROUP_DESCRIPTIONS[network]="Network utilities"` should have scripts named `bin/omarchy-network-*`. The router automatically discovers these files when listing commands for that group.