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

> Extend Omarchy CLI functionality by creating custom commands and groups. Learn the naming conventions and metadata requirements to build your own executable scripts for enhanced workflows.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: how-to-guide
- Published: 2026-09-12

---

**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 `exec`s 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`](https://github.com/omacom/omarchy/blob/main/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:

```bash
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:

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

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

```bash
omarchy hello world Alice

```

### 4. Validate Your Implementation

Run the CLI lint to verify metadata integrity:

```bash
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:

```bash
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`](https://github.com/omacom/omarchy/blob/main/agents/skills/command-metadata.md), with additional routing documentation available in [`docs/cli-router.md`](https://github.com/omacom/omarchy/blob/main/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.