How to Extend Omarchy CLI Functionality: Adding Custom Commands and Groups

To extend Omarchy CLI functionality, create an executable script in the bin/ directory following the omarchy-<group>-<verb> naming pattern, include metadata comments within the first 80 lines, and register new groups in the GROUP_DESCRIPTIONS array inside bin/omarchy.

The Omarchy project from omacom/omarchy provides a lightweight, extensible command-line interface that automatically discovers and dispatches commands based on executable filenames. Understanding how to extend Omarchy CLI functionality allows developers to add custom automation, integrate new workflows, and expand the tool's capabilities without modifying the core router logic.

Understanding the Omarchy CLI Architecture

The Router Script (bin/omarchy)

The core dispatch mechanism resides in bin/omarchy, which scans the bin/ directory for executables prefixed with omarchy-. When a user invokes a command, the router performs longest-prefix matching to resolve the target, falling back to a full metadata table when the fast-path filename probe (omarchy-<group>-<name>) fails. This design enables automatic command registration without explicit route definitions, as the router ultimately execs the matching binary directly.

Command Groups and Metadata System

The CLI organizes commands into functional groups using the GROUP_DESCRIPTIONS associative array defined in bin/omarchy (lines 29-97). Each entry maps a group name to a human-readable description for the top-level help listing. Hidden groups—such as apply and provision—deliberately omit entries here to stay out of public listings.

Individual commands expose metadata through special comment directives placed within the first 80 lines of each script. The complete specification lives in agents/skills/command-metadata.md, allowing the router to extract summaries, arguments, examples, and visibility flags without executing the script.

How to Add a New Command to Omarchy

1. Create the Executable File

Place your script in the bin/ directory using the naming convention omarchy-<group>-<verb>. For root-level group commands, use omarchy-<group>. Ensure the file is executable:

chmod +x bin/omarchy-mygroup-mycommand

2. Add Required Metadata Comments

Begin your script with structured metadata comments using the # omarchy:key=value syntax. The router reads only the first 80 lines, so place these directives immediately after the shebang:

#!/usr/bin/env bash

# omarchy:summary=One-line description for listings

# omarchy:args=<required_arg> [optional_arg]

# omarchy:examples=omarchy mygroup mycommand example-arg

# omarchy:hidden=true

# omarchy:requires-sudo=true

Required keys include summary (mandatory for passing omarchy commands --check), while args, examples, hidden, and requires-sudo provide additional context for help generation and execution validation.

3. Implement Command Logic

Write your business logic below the metadata. The router executes the matched script directly, passing all arguments after the command path. Access arguments using standard positional parameter syntax ($1, $2, etc.).

Here is a complete example implementing a greeting command:

#!/usr/bin/env bash

# omarchy:summary=Print a friendly greeting

# omarchy:args=<name>

# omarchy:examples=omarchy hello world Alice

# Bail out if the required argument is missing

if [[ -z $1 ]]; then
  echo "Usage: omarchy hello world <name>"
  exit 1
fi

echo "Hello, $1! Welcome to Omarchy."

Save this as bin/omarchy-hello-world, make it executable, and invoke it via:

omarchy hello world Alice

4. Validate Your Implementation

Run the CLI lint to verify metadata integrity:

omarchy commands --check

The test suite in test/cli also catches missing summaries or malformed boolean values in metadata directives.

How to Add a New Command Group

When creating commands for a functional area that does not exist, you must expose the group in the top-level help listing. Edit bin/omarchy around line 30 and add an entry to the GROUP_DESCRIPTIONS array:

GROUP_DESCRIPTIONS[mygroup]="My custom group description"

Any executable matching omarchy-mygroup-* automatically appears under this heading when users run omarchy --help. Groups without entries remain hidden but functional, useful for internal or provisional commands.

CLI Metadata Specification Reference

The metadata system supports these directive keys:

• summary – One-line description displayed in command listings. Required for visibility in omarchy commands --check.
• args – Human-readable argument specification shown in help text.
• examples – Sample invocations demonstrating proper usage.
• hidden – Set to true to exclude the command from public listings.
• requires-sudo – Set to true if the command requires elevated privileges.

These directives follow the pattern # omarchy:key=value and must appear within the first 80 lines of the script.

Summary

• Automatic Discovery: The Omarchy CLI router (bin/omarchy) automatically registers any executable in bin/ prefixed with omarchy-, using longest-prefix matching to resolve command paths.
• Metadata-Driven: Commands define behavior through structured comments in the first 80 lines, specifying summaries, arguments, examples, and visibility flags without external configuration files.
• Group Registration: New functional groups require entries in the GROUP_DESCRIPTIONS associative array within bin/omarchy (lines 29-97) to appear in public help listings.
• Validation: Use omarchy commands --check and the test/cli suite to verify metadata compliance and prevent malformed command registrations.

Frequently Asked Questions

How does the Omarchy CLI router resolve ambiguous command names?

The router employs longest-prefix matching with a fast-path filename probe for omarchy-<group>-<name> patterns. If the fast path fails, it falls back to a full metadata table scan. This resolution logic also handles --help, --json, and -- argument separators according to the implementation in bin/omarchy.

What naming convention must I follow to extend Omarchy CLI functionality?

Create executable files in the bin/ directory using the pattern omarchy-<group>-<verb> for subcommands or omarchy-<group> for root group commands. The filename segments determine the command structure invoked via omarchy <group> <verb>.

Where are command metadata specifications documented?

The authoritative metadata specification resides in agents/skills/command-metadata.md, with additional routing documentation available in docs/cli-router.md. These files define the supported # omarchy:key=value directives parsed from the first 80 lines of each command script.

Can I hide custom commands from the Omarchy help listing?

Yes. Set # omarchy:hidden=true in the command's metadata to hide individual commands. For entire groups, omit the group from the GROUP_DESCRIPTIONS array in bin/omarchy, which keeps the group functional but invisible in omarchy --help output.

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