How to Add a New CLI Command to the Omarchy Binary: A Complete Guide

To add a new CLI command to the Omarchy binary, create an executable Bash script in the bin/ directory following the omarchy-<group>-<command> 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 <group> <command>, 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 execs 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-<group>-<command> for subcommands, or omarchy-<group> 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=<name> – The command category (e.g., example)

• # omarchy:name=<name> – The specific command name (e.g., hello)

• # omarchy:summary=<text> – 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=<true|false>`` – Whether sudo is required

• # omarchy:hidden=<true|false> – Hide from command listings

Step 3: Set Execute Permissions

Make your script executable so the load_commands loop will discover it:

chmod +x bin/omarchy-example-hello

Step 4: Validate and Test

Verify the command appears in the CLI by running:

omarchy commands --all

Run omarchy commands --check to validate metadata for collisions and missing fields. Test your command directly:

omarchy example hello Alice

Complete Implementation Example

Below is a minimal working example that implements a hello command under the example group.

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

$ 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-<group> and set group=<group> in the metadata. The dispatcher treats the filename root as both the group and command name, routing omarchy <group> 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-<group>-<command> for subcommands or omarchy-<group> 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-<group>-<command> for subcommands or omarchy-<group> 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 <group> without a subcommand, name the file omarchy-<group> (e.g., bin/omarchy-greet) and set # omarchy:group=<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 <group> <command> --help to verify the auto-generated help text renders correctly.

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