Omarchy Command Metadata Convention: Complete Guide to Script Headers

The Omarchy metadata convention uses # omarchy:key=value comment headers in Bash scripts to define command attributes like group, name, summary, and arguments, which the central router parses to build the command registry.

All Omarchy commands are Bash scripts stored in the bin/ directory. Each script declares its identity and behavior through a metadata header that the command router (bin/omarchy) scans at runtime. This convention enables automatic command discovery, help generation, and routing without external configuration files.

How the Router Parses Metadata Headers

The metadata discovery happens in bin/omarchy at lines 1900–1905, where the router reads the first approximately 80 non-empty comment lines of each script. It extracts lines matching the strict pattern:

# omarchy:<key>=<value>

Keys and values are separated by an equals sign. No spaces are permitted around the equals sign. The router populates the command registry from these declarations, falling back to filename-derived defaults when keys are absent.

Supported Metadata Keys

Key	Purpose	Default Behavior
group	Command category (e.g., theme, launch)	Derived from script filename
name	Command verb (e.g., list, set)	Derived from script filename
summary	Short description for omarchy commands	First non-metadata comment line
args	Usage string with argument definitions	None (command takes no arguments)
examples	Sample invocations separated by |	None
alias / aliases	Alternative routes resolving to this command	None
requires-sudo	Elevated privileges required	false
hidden	Exclude from default command listing	false

The args field supports optional argument notation: arguments wrapped in [...] brackets are treated as optional. The router strips these brackets to determine whether a command requires arguments.

For alias and aliases, multiple values use the pipe character \| as a delimiter. These create alternate routes that resolve to the same underlying command script.

Metadata Declaration Examples

Minimal Metadata (Automatic Naming)

When group and name are omitted, the router derives them from the filename omarchy-screenshot-capture:

#!/usr/bin/env bash

# omarchy:summary=Take a screenshot

# omarchy:args=[--full] [--output=FILE]

echo "Capturing screenshot..."

This registers as omarchy screenshot capture with optional --full and --output flags.

Complete Metadata Declaration

Full control over routing and presentation:

#!/usr/bin/env bash

# omarchy:group=theme

# omarchy:name=set

# omarchy:summary=Apply a color theme

# omarchy:args=THEME_NAME

# omarchy:examples=omarchy theme set dark|omarchy theme set solarized

# omarchy:aliases=apply|use

# omarchy:requires-sudo=true

# omarchy:hidden=false

# Implementation requires elevated privileges to modify system themes

sudo tee /etc/omarchy/theme.conf <<< "$1"

This command registers under theme set, responds to theme apply and theme use, requires sudo, and displays rich help with examples.

Hidden Command with Alias-Only Access

Commands intended for internal use or advanced users:

#!/usr/bin/env bash

# omarchy:group=dev

# omarchy:name=debug

# omarchy:summary=Print debugging information

# omarchy:hidden=true

# omarchy:aliases=info|diagnostic

# Hidden from omarchy commands listing

omarchy-system-dump "$@"

Users discover this via omarchy dev info or omarchy dev diagnostic, but it never appears in default command listings.

Key Files in the Metadata System

File	Role
bin/omarchy	Central router implementing metadata parsing (lines 1900–2042)
bin/omarchy-*	Individual command scripts containing metadata headers

The router's fallback summary logic (beginning at line 2042) extracts the first regular comment line when no summary key is present. This ensures every command has descriptive text even with minimal metadata.

Common Patterns and Best Practices

Derive from filename when possible. The automatic group/name extraction from omarchy-{group}-{name} filenames reduces boilerplate. Only override group or name when the filename convention cannot express the desired routing.

Use pipe separators consistently. Both examples and aliases use \| as a delimiter. The router splits on this character to build lists for help output.

Validate requires-sudo strictly. The router accepts only true as a valid value for this key. Any other value triggers an error report during command registration.

Combine hidden with aliases for power-user features. This pattern surfaces advanced functionality through intentional discovery paths while keeping the default interface clean.

Summary

• Omarchy commands declare metadata in # omarchy:key=value comment headers

• The router scans the first ~80 comment lines of each bin/omarchy-* script

• Supported keys cover grouping, naming, documentation, privileges, and visibility

• Filename-derived defaults reduce repetition for standard naming conventions

• Implementation resides in bin/omarchy with parsing logic at lines 1900–2042

Frequently Asked Questions

What happens if I omit the metadata header entirely?

The command still functions. The router derives group and name from the script filename using the omarchy-{group}-{name} pattern, attempts to extract a summary from the first non-metadata comment line, and assumes no arguments, aliases, or special requirements. This minimal approach works for simple utilities.

Can I use spaces in metadata values?

Yes, for values like summary and args. The parser treats everything after the first = as the value. However, do not include spaces around the equals sign in the key declaration. Use # omarchy:summary=My description not # omarchy:summary = My description.

How do I mark a command as requiring root privileges?

Add # omarchy:requires-sudo=true to the metadata header. The router records this flag, and the help system can alert users. Note that Omarchy does not automatically invoke sudo; your script must still execute sudo commands as needed. Only the literal string true is accepted—other values produce errors.

Why would I hide a command from the default listing?

Use # omarchy:hidden=true for experimental features, deprecated commands maintained for compatibility, or internal utilities not meant for general use. Combine with aliases to provide intentional access paths for users who need these capabilities, as demonstrated in the Hidden Command with Alias-Only Access pattern above.

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