# How to Add a New Command Prefix to the Omarchy CLI Router with GROUP_DESCRIPTIONS

> Learn to add a new command prefix to the Omarchy CLI router using GROUP_DESCRIPTIONS. Register your group and create executable scripts in bin/ to extend functionality.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: how-to-guide
- Published: 2026-09-09

---

**To add a new command prefix to the Omarchy CLI router, you must register the group name in the `GROUP_DESCRIPTIONS` associative array inside `bin/omarchy` and create executable scripts named `omarchy-<group>-<verb>` in the `bin/` directory.**

The **omacom/omarchy** repository uses a convention-based CLI router that automatically discovers commands from the filesystem. When you add a new command prefix (the group segment), the `GROUP_DESCRIPTIONS` array provides the human-readable titles that appear in help output, making this registration step essential for the router to recognize and display your new command group.

## Understanding the Omarchy CLI Router Architecture

The Omarchy CLI router builds its command hierarchy from two distinct sources:

- **Executable filenames** in `bin/` that follow the pattern `omarchy-<group>-<verb>`
- **Human-readable titles** stored in the associative array `GROUP_DESCRIPTIONS` inside the central router script `bin/omarchy` (lines 27‑94)

According to the source code in `bin/omarchy`, the router iterates through the `bin/` directory to discover available verbs, then uses `GROUP_DESCRIPTIONS` to map the group segment to descriptive text for help generation. Without an entry in this associative array, your new group will not appear in `omarchy --help` output or group-specific help pages.

## Step-by-Step Guide to Adding a New Command Prefix

### Step 1: Register the Group in GROUP_DESCRIPTIONS

Edit `bin/omarchy` and add your new group to the `declare -A GROUP_DESCRIPTIONS` block. This registration enables the router to list the group in help output.

```bash

# Inside bin/omarchy, approximately line 90

GROUP_DESCRIPTIONS[dotfiles]="Dotfiles management (install, update, remove)"

```

The key (`dotfiles` in this example) becomes the command prefix, while the value provides the descriptive text shown to users.

### Step 2: Create Command Scripts for Your Verbs

Add executable scripts to `bin/` following the naming convention `omarchy-<group>-<verb>`. Each script must include metadata comments that the router parses for help generation.

```bash
#!/usr/bin/env bash

# omarchy:summary="Install my curated dotfiles"

# omarchy:description="Copies a set of configuration files into $HOME"

# omarchy:hidden=false

set -euo pipefail

# Implementation logic here

```

Save this as `bin/omarchy-dotfiles-install` and ensure the file is executable (`chmod +x`). The router discovers these files automatically and extracts the `omarchy:summary` and `omarchy:description` values for command listings.

### Step 3: Hide Internal Plumbing Commands (Optional)

If you need helper scripts that should not appear in public help output, add the hidden metadata comment at the top of the file. This keeps the public CLI surface clean while allowing other scripts to invoke the command internally.

```bash
#!/usr/bin/env bash

# omarchy:hidden=true

set -euo pipefail

# Internal helper implementation

```

Scripts marked with `# omarchy:hidden=true` remain functional but are excluded from the auto-generated help table in `omarchy --help` and group-specific help pages.

### Step 4: Update Documentation

Add a short entry to [`docs/cli-router.md`](https://github.com/omacom/omarchy/blob/main/docs/cli-router.md) describing the new group and its intended verbs. Since the documentation references the `GROUP_DESCRIPTIONS` table, your new entry will appear automatically in the generated help system once registered in Step 1. This ensures users can discover the new functionality through standard documentation channels.

### Step 5: Validate with Tests

Execute the CLI test suite to verify your new group appears correctly and that its verbs execute without errors.

```bash
./test/cli

```

This guarantees that your addition does not break the router's command discovery mechanism or existing command functionality.

## Complete Working Example

Here is a complete example adding a `dotfiles` group that manages dot-file operations:

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

```bash
GROUP_DESCRIPTIONS[dotfiles]="Dotfiles management (install, update, remove)"

```

**2. Create the install command at `bin/omarchy-dotfiles-install`:**

```bash
#!/usr/bin/env bash

# omarchy:summary="Install curated dotfiles"

# omarchy:description="Copies configuration files into $HOME/.config"

# omarchy:hidden=false

set -euo pipefail

echo "Installing dotfiles..."

# Copy logic here

```

**3. Create an internal helper at `bin/omarchy-dotfiles-helper` (hidden):**

```bash
#!/usr/bin/env bash

# omarchy:hidden=true

set -euo pipefail

# Internal validation logic

```

After adding these files, running `omarchy dotfiles` lists the available verbs (`install`), and `omarchy --help` displays the group title "Dotfiles management (install, update, remove)".

## Key Files Reference

| File | Role |
|------|------|
| `bin/omarchy` | Central router script; defines `GROUP_DESCRIPTIONS` (lines 27‑94) and prints the help table |
| `bin/omarchy-<group>-<verb>` | Individual command scripts discovered by the router |
| [`docs/cli-router.md`](https://github.com/omacom/omarchy/blob/main/docs/cli-router.md) | Documentation of the CLI routing mechanism and `GROUP_DESCRIPTIONS` usage |
| [`docs/file-layout.md`](https://github.com/omacom/omarchy/blob/main/docs/file-layout.md) | Repository layout overview, including command script locations |

## Summary

- **`GROUP_DESCRIPTIONS`** in `bin/omarchy` is the authoritative registry for command group metadata, required for groups to appear in help output
- **Command scripts** must follow the `omarchy-<group>-<verb>` naming convention and reside in `bin/`
- **Metadata comments** (`omarchy:summary`, `omarchy:description`, `omarchy:hidden`) control how commands appear in help tables
- **Hidden commands** support internal plumbing while keeping public interfaces clean
- **Testing** via `./test/cli` ensures new prefixes integrate correctly with the router

## Frequently Asked Questions

### What file naming convention must I follow for new commands?

You must name executable scripts `omarchy-<group>-<verb>` and place them in the `bin/` directory. The router splits the filename on hyphens to extract the group (prefix) and verb (action), then matches the group against keys in `GROUP_DESCRIPTIONS` to generate help text.

### How does the router discover available commands?

The router scans the `bin/` directory for files matching the `omarchy-*` pattern at runtime. It parses each filename to determine group and verb relationships, then uses the `GROUP_DESCRIPTIONS` associative array defined in `bin/omarchy` (lines 27‑94) to retrieve human-readable titles for help generation.

### Can I hide commands from the help output?

Yes. Add `# omarchy:hidden=true` as a metadata comment at the top of the script. Hidden commands remain executable and callable by other scripts but are excluded from `omarchy --help` and group-specific help listings, allowing you to maintain clean public interfaces while supporting internal plumbing.

### Where is GROUP_DESCRIPTIONS defined?

The `GROUP_DESCRIPTIONS` associative array is defined in `bin/omarchy` between lines 27 and 94. This array maps command group prefixes to descriptive strings used in the auto-generated help system. Any new command prefix must be registered here before it will appear in help output.