How Omarchy Commands Define Metadata: The Complete Guide to # omarchy: Comments

Omarchy commands embed descriptive metadata directly in script files using special # omarchy: comment prefixes, which the main bin/omarchy router parses to generate help text, argument validation, and menu organization.

The basecamp/omarchy repository implements a self-documenting CLI framework where each command script carries its own specification. This design eliminates external configuration files by storing Omarchy command metadata in structured comment headers that the router extracts at runtime.

The # omarchy: Comment Convention

Every Omarchy command script begins with a block of comments starting with # omarchy:. These lines follow a strict key=value syntax that declares everything from user-facing descriptions to runtime requirements.

Core Metadata Keys

The parser recognizes several standard keys that control command behavior and visibility:

• summary – A one-sentence description displayed in command listings. Example: # omarchy:summary=Install, launch, stop, inspect, or remove the Windows VM

• args – Argument syntax hints shown in help output. Example: # omarchy:args=<install|remove|launch|stop|status> [options]

• requires-sudo – Boolean flag indicating elevated privileges are required. Example: # omarchy:requires-sudo=true

• hidden – When set to true, excludes the command from public menus. Example: # omarchy:hidden=true

• group – Logical grouping for menu organization (e.g., transcode, webapp). Example: # omarchy:group=transcode

• name – Explicit sub-command name when a single file implements multiple verbs. Example: # omarchy:name=ascii

• examples – Usage examples appearing in help documentation. Example: # omarchy:examples=omarchy transcode ascii ~/logo.svg /tmp/logo.txt

How the bin/omarchy Router Parses Metadata

The metadata extraction logic lives in bin/omarchy, specifically within the initialization routines that build the command registry. The router performs four distinct operations when loading commands:

1. Directory Traversal – The script locates executable files matching the omarchy-<group>-<verb> naming convention within the bin/ directory.
2. Comment Block Extraction – For each command file, the parser reads lines sequentially until encountering a non-comment line, capturing any line matching the ^#\ omarchy:(.+)=(.+)$ pattern.
3. Associative Array Population – Extracted key-value pairs populate namespaced associative arrays using dynamic variable naming (e.g., CMD_SUMMARY, CMD_ARGS, CMD_HIDDEN).
4. Group Description Integration – The GROUP_DESCRIPTIONS associative array, defined at line 27 in bin/omarchy, maps group identifiers to human-readable menu headings.

The parsing implementation uses Bash regex matching to isolate keys and values:

# Excerpt from bin/omarchy showing metadata extraction

while IFS= read -r line; do
    [[ $line =~ ^#\ omarchy:(.+)=(.+)$ ]] && {
        key=${BASH_REMATCH[1]}
        val=${BASH_REMATCH[2]}
        declare -g "CMD_${key^^}[$cmd]=$val"
    }
done < <(head -n 20 "$cmd_path")

Real-World Command Metadata Example

The bin/omarchy-windows-vm command demonstrates a complete metadata block at the beginning of the script:

#!/usr/bin/env bash

# omarchy:summary=Manage the Windows development VM

# omarchy:args=<install|remove|launch|stop|status> [--memory=8G]

# omarchy:requires-sudo=true

# omarchy:group=vm

omarchy-windows-vm() {
    # Command implementation follows metadata

    case "$1" in
        install) install_vm "$2" ;;
        # ...

    esac
}

Similarly, bin/omarchy-transcode utilizes advanced keys for sub-command routing and grouping:

#!/usr/bin/env bash

# omarchy:summary=Convert media files to different formats

# omarchy:args=<input> <output> [--format=mp4]

# omarchy:group=media

# omarchy:name=transcode

# omarchy:examples=omarchy transcode input.avi output.mp4

omarchy-transcode() {
    ffmpeg -i "$1" "$3" "$2"
}

These examples illustrate how Omarchy command metadata remains co-located with implementation logic, ensuring documentation stays synchronized with code changes.

Summary

• Omarchy uses # omarchy: comment prefixes to embed metadata directly in command scripts, eliminating separate configuration files.

• The bin/omarchy router parses these comments into associative arrays to generate help text, validate arguments, and organize menu groups.

• Supported keys include summary, args, requires-sudo, hidden, group, name, and examples.

• The GROUP_DESCRIPTIONS array at line 27 of the main router defines human-readable headings for command groups.

• Commands following the omarchy-<group>-<verb> naming convention are automatically discovered and cataloged based on their metadata headers.

Frequently Asked Questions

What is the exact syntax for Omarchy metadata comments?

Each metadata line must begin with # omarchy: followed immediately by a key, an equals sign, and a value with no spaces around the equals sign. For example: # omarchy:summary=Manage virtual machines. The parser uses the regex pattern ^#\ omarchy:(.+)=(.+)$, so keys and values cannot contain unescaped equals signs or omit the prefix.

How does Omarchy handle commands that require root privileges?

When a command script includes # omarchy:requires-sudo=true, the bin/omarchy router checks the effective UID before executing the command function. If the user lacks superuser privileges, the router emits a permission error and exits before invoking the command implementation, providing a consistent security boundary across the CLI.

Where is the metadata parser implemented in the source code?

The extraction logic resides in bin/omarchy within the command discovery loop. The GROUP_DESCRIPTIONS associative array initializes at line 27, while the regex-based parsing routine appears shortly after in the same file. This centralized parsing ensures all Omarchy commands receive uniform metadata processing regardless of their specific group or function.

Can a single Omarchy script define multiple sub-commands?

Yes. When a script implements multiple related verbs (such as omarchy-transcode handling both ascii and video conversions), use the # omarchy:name=<subcommand> key to declare distinct identities. The router treats each unique name value as a separate entry in the command registry, allowing one physical file to register multiple logical commands with independent metadata blocks.

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