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

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.

# 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.

#!/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.

#!/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 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.

./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:

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

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

#!/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):

#!/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	Documentation of the CLI routing mechanism and GROUP_DESCRIPTIONS usage
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.

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