GROUP_DESCRIPTIONS in Omarchy: How Command Group Metadata Shapes CLI Output

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:

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):

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):

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:

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:

$ 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:

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 — Explains that the table "also titles each group" (lines 101–106), providing architectural context for contributors.
• 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 and 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}