# Omarchy Command Metadata Convention: Complete Guide to Script Headers

> Discover the Omarchy command metadata convention. Learn how to use # omarchy:key=value script headers in Bash to define command attributes for the central router.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: deep-dive
- Published: 2026-09-02

---

**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:

```bash

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

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

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

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