How Omarchy CLI Command Groups Are Defined: A Deep Dive into the Architecture

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-<group>-<command> 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:

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-<group>-<command>

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:

# 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-<newgroup>-<command> 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:

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

$ omarchy hw
hw   – Hardware‑detection commands
  omarchy-hw-info    Display system hardware information
  omarchy-hw-sensors Read sensor data

Accessing utility commands:

$ 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-<group>-<command>
• 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 <group> 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.

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