How to Create Custom Groups for the Omarchy CLI

Yes, you can create custom command groups for the Omarchy CLI by adding entries to the GROUP_DESCRIPTIONS associative array in bin/omarchy and creating executable scripts prefixed with omarchy-<group>-<verb> in the bin/ directory.

The Omarchy CLI framework provides a modular, extensible command structure that allows developers to organize commands into logical groups. In the omacom/omarchy repository, the entire routing mechanism is driven by a single Bash script that discovers available groups through a declarative associative array. Understanding this architecture enables you to extend the CLI with your own custom command groups without modifying the core routing logic.

Understanding the CLI Router Architecture

The central entry point for all Omarchy CLI operations is the bin/omarchy script. This file defines the GROUP_DESCRIPTIONS associative array, which maps group names to human-readable descriptions used in help output and tab completion.

When a user executes omarchy <group> <verb>, the router performs the following operations:

1. Validates the <group> parameter against the keys in GROUP_DESCRIPTIONS
2. Scans the bin/ directory for executables matching the pattern omarchy-<group>-<verb>
3. Dispatches execution to the matching script if found

The router requires no additional registration steps—discovery is purely filesystem-based based on the naming convention and the associative array entries.

Adding a Custom Group to GROUP_DESCRIPTIONS

To create a new command group, edit bin/omarchy and add an entry to the GROUP_DESCRIPTIONS array. The syntax follows standard Bash associative array assignment:

GROUP_DESCRIPTIONS[mytool]="My personal tool collection"

Place this line alongside the existing group definitions in the file. The key (mytool in this example) becomes the command group identifier, while the value provides the description shown when users run omarchy help. This declaration is the only registry step required; the router automatically recognizes the new group on the next execution.

Implementing Verbs for Your Custom Group

Each verb within a group is implemented as a separate executable script in the bin/ directory. The filename must follow the strict convention omarchy-<group>-<verb>.

For example, to create a status verb for your mytool group:

1. Create the file bin/omarchy-mytool-status
2. Make it executable: chmod +x bin/omarchy-mytool-status
3. Add the required metadata comments and implementation:

#!/usr/bin/env bash

# omarchy:summary=Show status of MyTool

# omarchy:hidden=false

echo "MyTool is running version $(mytool --version)"

The # omarchy:summary= comment defines the help text for this specific verb. The # omarchy:hidden=false flag controls visibility in help listings (setting it to true suppresses display while keeping the command functional).

After creation, you can invoke the command immediately:

$ omarchy mytool status
MyTool is running version 1.4.2

Running omarchy help now displays your new group and its verbs:

$ omarchy help
...
mytool          My personal tool collection
...

Hiding Groups from Help Output

If you need a command to remain functional but hidden from casual users, modify the metadata header in the script:

# omarchy:hidden=true

The router respects this flag when generating help tables, filtering out any scripts marked as hidden. This is useful for administrative commands or experimental features that should not appear in standard omarchy help output.

Key Files and Conventions

• bin/omarchy — The central CLI router containing the GROUP_DESCRIPTIONS associative array and dispatch logic.
• bin/omarchy-<group>-<verb> — Individual command implementations that must be executable and follow the naming convention.
• docs/cli-router.md — Documentation covering the routing logic and GROUP_DESCRIPTIONS table structure.
• docs/file-layout.md — Overview of repository organization and CLI binary placement.

All custom scripts must reside in the bin/ directory at the repository root and include executable permissions. The router does not search subdirectories for command implementations.

Summary

• Custom groups are declared by adding entries to the GROUP_DESCRIPTIONS associative array inside bin/omarchy.

• Verbs are implemented as separate executable files named omarchy-<group>-<verb> in the bin/ directory.

• Scripts require metadata comments (# omarchy:summary=) for proper integration with the help system.

• The router discovers commands automatically through filesystem scanning; no runtime registration API exists.

• Use # omarchy:hidden=true to suppress specific commands from appearing in omarchy help listings.

Frequently Asked Questions

Can I add custom groups without modifying the Omarchy source code?

No. According to the current implementation in omacom/omarchy, adding custom groups requires direct modification of the bin/omarchy file. There is no exposed runtime API or configuration file for registering new groups dynamically. Any changes to GROUP_DESCRIPTIONS necessitate editing the source and re-executing the router.

What naming convention should I follow for custom command scripts?

You must use the pattern omarchy-<group>-<verb> where <group> matches exactly the key defined in GROUP_DESCRIPTIONS and <verb> describes the action. Place these files in the bin/ directory and ensure they have executable permissions (chmod +x). The router constructs the executable path by concatenating bin/omarchy-<group>-<verb> and checking for existence and execute permissions.

How does the Omarchy CLI discover commands for my custom group?

The router performs a filesystem scan of the bin/ directory looking for executables matching the glob pattern omarchy-<group>-*. It extracts the verb portion from the filename suffix (everything after the second hyphen) and parses the script headers for # omarchy:summary= comments to build the help output. This discovery happens at runtime, so new commands are available immediately after file creation without restarting any services.

Can I hide specific commands or groups from the help output while keeping them functional?

Yes. Add the comment # omarchy:hidden=true to the header of any command script. The router checks for this flag when generating help tables and excludes matching scripts from the display. The command remains fully executable via direct invocation (omarchy group verb) but will not appear in omarchy help listings, making it ideal for debugging utilities or administrative functions.

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