# How to Add a New CLI Command to the Omarchy Binary: A Complete Guide > Learn how to add a new CLI command to the omarchy binary. Create executable Bash scripts in bin/ and follow the naming convention to extend omarchy functionality. - Repository: [Omacom/omarchy](https://github.com/omacom/omarchy) - Tags: how-to-guide - Published: 2026-09-11 --- **To add a new CLI command to the Omarchy binary, create an executable Bash script in the `bin/` directory following the `omarchy--` naming convention and include specially formatted metadata comments that the dispatcher automatically discovers and parses.** Omarchy's command-line interface implements a file-based discovery system that eliminates the need to modify the central dispatcher when extending functionality. According to the Omarchy source code, the `bin/omarchy` dispatcher script dynamically registers commands by scanning for executable files prefixed with `omarchy-`. This architecture allows developers to add new CLI commands by simply creating appropriately named scripts with structured metadata comments. ## Understanding the Omarchy CLI Dispatcher The core dispatcher at `bin/omarchy` implements a three-phase command resolution system. At startup, the **`load_commands`** function (lines 18-21) scans the `bin/` directory for any executable whose name begins with `omarchy-`. Each discovered script is passed to **`register_command`** (lines 69-78), which parses the metadata comments formatted as `# omarchy:key=value` lines to build internal routing tables. When a user executes `omarchy `, the **`dispatch_or_help`** function (lines 12-14) resolves the route against these tables. If the user passes `--help` or `-h`, the dispatcher generates help text automatically. Otherwise, it `exec`s the underlying binary directly. This design means you never need to modify `bin/omarchy` itself when adding new functionality. ## Step-by-Step Guide to Adding a New Command Follow these four steps to register a new command in the Omarchy CLI. ### Step 1: Create the Command File Create a new executable script in the `bin/` directory. The filename must follow the pattern `omarchy--` for subcommands, or `omarchy-` for group-only commands. For example, to create a `hello` command under the `example` group, name the file `bin/omarchy-example-hello`. ### Step 2: Define Metadata Comments Add structured metadata comments at the top of your script. The dispatcher reads these comments in `register_command` to build help text and routing tables. Required and optional metadata keys include: - **`# omarchy:group=`** – The command category (e.g., `example`) - **`# omarchy:name=`** – The specific command name (e.g., `hello`) - **`# omarchy:summary=`** – Brief description for help listings - **`# omarchy:args=[param1] [param2]`** – Argument signatures - **`# omarchy:examples=cmd1|cmd2`** – Usage examples separated by pipes - **`# omarchy:aliases=alias1|alias2`** – Alternative command names - **`# omarchy:requires-sudo=``** – Whether sudo is required - **`# omarchy:hidden=`** – Hide from command listings ### Step 3: Set Execute Permissions Make your script executable so the `load_commands` loop will discover it: ```bash chmod +x bin/omarchy-example-hello ``` ### Step 4: Validate and Test Verify the command appears in the CLI by running: ```bash omarchy commands --all ``` Run `omarchy commands --check` to validate metadata for collisions and missing fields. Test your command directly: ```bash omarchy example hello Alice ``` ## Complete Implementation Example Below is a minimal working example that implements a `hello` command under the `example` group. ```bash #!/usr/bin/env bash # omarchy:group=example # omarchy:name=hello # omarchy:summary=Print a friendly greeting # omarchy:args=[name] # omarchy:examples=omarchy example hello Alice | omarchy example hello # omarchy:aliases=greet|hi # omarchy:requires-sudo=false # omarchy:hidden=false # Default to "World" if no name is supplied NAME="${1:-World}" printf 'Hello, %s!\n' "$NAME" ``` Save this as `bin/omarchy-example-hello`, make it executable, and the command becomes immediately available: ```bash $ omarchy example hello Alice Hello, Alice! $ omarchy example hello Hello, World! $ omarchy example hello --help Usage: omarchy example hello [name] Print a friendly greeting ``` ## Advanced: Group-Only Commands To create a command that responds directly to a group name without a subcommand (e.g., `omarchy greet` instead of `omarchy greet something`), name the file `omarchy-` and set `group=` in the metadata. The dispatcher treats the filename root as both the group and command name, routing `omarchy ` calls directly to your script. ## Summary - **Omarchy uses file-based discovery**: The `bin/omarchy` dispatcher automatically finds and registers any executable file in `bin/` matching the `omarchy-*` pattern. - **Metadata drives functionality**: Comments formatted as `# omarchy:key=value` define routing, help text, and command behavior without modifying the dispatcher. - **Naming dictates structure**: Use `omarchy--` for subcommands or `omarchy-` for standalone group commands. - **Validation is built-in**: Use `omarchy commands --check` to validate metadata and `omarchy commands --all` to verify registration. ## Frequently Asked Questions ### What is the exact file naming convention for Omarchy CLI commands? Omarchy CLI commands must reside in the `bin/` directory and follow the naming pattern `omarchy--` for subcommands or `omarchy-` for group-only commands. The dispatcher at `bin/omarchy` scans for this prefix during the `load_commands` initialization phase (lines 18-21). ### What metadata fields are required when adding a new command? The `register_command` function (lines 69-78) requires at minimum `# omarchy:group=` and `# omarchy:name=` to build the routing table. While only these two keys are strictly necessary for registration, you should include `# omarchy:summary=` for help generation and `# omarchy:args=` for argument documentation to ensure a complete user experience. ### How do I create a group-only command without a subcommand? To create a command accessible directly via `omarchy ` without a subcommand, name the file `omarchy-` (e.g., `bin/omarchy-greet`) and set `# omarchy:group=` in the metadata. The dispatcher interprets this pattern as both the group identifier and the default command for that group. ### How can I validate my new command before committing? Run `omarchy commands --check` to validate your metadata for missing fields, naming collisions, and syntax errors in the comment blocks. Then execute `omarchy commands --all` to confirm your new command appears in the registry and `omarchy --help` to verify the auto-generated help text renders correctly.