# How to Create Custom Groups for the Omarchy CLI > Learn to create custom groups for Omarchy CLI commands. Add entries to GROUP_DESCRIPTIONS and create scripts in bin to extend Omarchy's functionality. - Repository: [Omacom/omarchy](https://github.com/omacom/omarchy) - Tags: how-to-guide - Published: 2026-08-30 --- **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--` 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 `, the router performs the following operations: 1. Validates the `` parameter against the keys in `GROUP_DESCRIPTIONS` 2. Scans the `bin/` directory for executables matching the pattern `omarchy--` 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: ```bash 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--`. 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: ```bash #!/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: ```bash $ omarchy mytool status MyTool is running version 1.4.2 ``` Running `omarchy help` now displays your new group and its verbs: ```bash $ 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: ```bash # 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--`** — Individual command implementations that must be executable and follow the naming convention. - **[`docs/cli-router.md`](https://github.com/omacom/omarchy/blob/main/docs/cli-router.md)** — Documentation covering the routing logic and `GROUP_DESCRIPTIONS` table structure. - **[`docs/file-layout.md`](https://github.com/omacom/omarchy/blob/main/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--` 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--` where `` matches exactly the key defined in `GROUP_DESCRIPTIONS` and `` 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--` 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--*`. 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.