# Omarchy Command Metadata: Complete Guide to Available Fields and Usage

> Explore Omarchy command metadata fields for automatic help generation, shell completion, and more. Discover how to leverage built-in comments for enhanced command functionality.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: api-reference
- Published: 2026-08-31

---

**Omarchy commands expose a standardized set of metadata fields embedded as comment headers, enabling automatic help generation, shell completion, privilege checking, and command grouping without external configuration files.**

The Omarchy CLI framework uses self-documenting executable scripts where metadata is parsed directly from source code comments. This design eliminates the need for separate manifest files while keeping command definitions portable and version-controlled alongside the code itself.

## Core Metadata Fields in Omarchy Commands

Every Omarchy command script supports a consistent vocabulary of metadata headers. These headers follow the pattern `# omarchy:<key>=<value>` and must appear at the top of the file, before any executable code.

### Required and Active Fields

| Field | Purpose | Example Value |
|-------|---------|---------------|
| `omarchy:summary` | One-sentence description for help listings | `Install, launch, stop, inspect, or remove the Windows VM` |
| `omarchy:args` | Positional argument specification for completions | `<install\|remove\|launch\|stop\|status> [options]` |
| `omarchy:name` | Override for the inferred command name | `omarchy-windows-key` |
| `omarchy:group` | Explicit command group assignment | `windows` |
| `omarchy:hidden` | Excludes command from default help output | `true` |
| `omarchy:requires-sudo` | Declares elevation requirement | `true` |

### Deprecated and Removed Fields

The Omarchy codebase has progressively simplified its metadata schema. The following fields are no longer processed by the router in `bin/omarchy`:

- `omarchy:visibility` — replaced by `hidden`
- `omarchy:mutates` — removed; state-change warnings now handled differently
- `omarchy:interactive` — removed; interactivity detected at runtime
- `omarchy:legacy` — removed; legacy detection now file-based
- `omarchy:usage` — removed; router builds usage strings from `args`
- `omarchy:binary` — removed; binary path always inferred from file location

The test suite in `test/cli` enforces that no deprecated fields appear in new command scripts.

## How Omarchy Parses Command Metadata

The central router script `bin/omarchy` implements the metadata extraction logic. When you run `omarchy commands --check` or trigger shell completion, the router performs these operations:

1. **File discovery** — scans `bin/` for files matching the `omarchy-*` naming pattern
2. **Header extraction** — reads comment lines starting with `# omarchy:` until the first non-comment line

3. **Name inference** — derives the command name from the filename (`omarchy-<group>-<verb>`) unless `omarchy:name` overrides it
4. **Group assignment** — uses the file prefix or `omarchy:group` value to categorize commands
5. **Privilege validation** — checks `omarchy:requires-sudo` before execution when the router is invoked with `--sudo-check`

The router also maintains an associative array `GROUP_DESCRIPTIONS` that maps group identifiers to human-readable descriptions, separate from per-command metadata.

## Practical Metadata Examples

### Minimal Command Definition

```bash
#!/bin/bash

# omarchy:summary=Returns a formatted weather status string with temperature and wind speed.

# omarchy:args=

# Command implementation follows...

echo "Weather: 72°F, wind 8mph NW"

```

The `omarchy:args=` line with an empty value indicates the command accepts no positional arguments.

### Full Privileged Command with Hidden Status

```bash
#!/bin/bash

# omarchy:summary=Install, launch, stop, inspect, or remove the Windows VM

# omarchy:args=<install|remove|launch|stop|status> [options]

# omarchy:requires-sudo=true

# omarchy:hidden=true

# Implementation requires elevated privileges for VM management...

```

This command will not appear in default `omarchy --help` output but remains accessible via explicit invocation and shell completion when partially typed.

### Programmatic Metadata Access

```bash
#!/bin/bash

# Extract metadata from any Omarchy command for custom tooling

command_path=$(which omarchy-windows-vm)

# Parse summary line

summary=$(grep -m1 '^# omarchy:summary=' "$command_path" | cut -d= -f2-)

# Parse argument specification

args=$(grep -m1 '^# omarchy:args=' "$command_path" | cut -d= -f2-)

# Check sudo requirement

requires_sudo=$(grep -m1 '^# omarchy:requires-sudo=' "$command_path" | cut -d= -f2-)

echo "Command: $command_path"
echo "Summary: $summary"
echo "Usage: omarchy-windows-vm $args"
[[ "$requires_sudo" == "true" ]] && echo "Requires: sudo privileges"

```

## Key Source Files for Omarchy Metadata

| File Path | Responsibility |
|-----------|--------------|
| `bin/omarchy` | Central router; parses metadata headers, defines `GROUP_DESCRIPTIONS`, implements `--check` validation |
| [`agents/skills/command-metadata.md`](https://github.com/omacom/omarchy/blob/main/agents/skills/command-metadata.md) | Formal specification of supported metadata fields and validation rules |
| `test/cli` | Automated test suite verifying metadata completeness and absence of deprecated fields |
| `bin/omarchy-windows-vm` | Example command script demonstrating full metadata usage |
| `bin/omarchy-weather-status` | Example of minimal metadata configuration |

## Summary

- **Six active metadata fields** define Omarchy command behavior: `summary`, `args`, `name`, `group`, `hidden`, and `requires-sudo`
- **Comment-based embedding** keeps metadata colocated with implementation, eliminating external manifests
- **Automatic inference** provides defaults for name and group when explicit metadata is omitted
- **Strict validation** in `test/cli` prevents deprecated field usage and enforces required `summary` presence
- **Router-driven parsing** in `bin/omarchy` enables help generation, completion, and privilege checking from a single source of truth

## Frequently Asked Questions

### What happens if I omit the `omarchy:summary` field?

The `test/cli` validation suite will fail, and the command will not be included in help listings. The `omarchy commands --check` command specifically flags missing summaries as errors.

### Can I use multiline values for metadata fields?

No. Each `omarchy:` header must fit on a single comment line. For complex descriptions, use concise single-sentence summaries; extended documentation belongs in the command's internal help text or man page.

### How does `omarchy:group` interact with the filename prefix?

The explicit `omarchy:group` value overrides any group derived from the filename. A file named `omarchy-network-dns` with `# omarchy:group=system` will be categorized under the `system` group rather than `network`.

### Why are some metadata fields like `omarchy:visibility` deprecated?

Early Omarchy versions used separate fields for overlapping concerns. The schema was consolidated to reduce parsing complexity and prevent conflicting declarations—`hidden` now unambiguously controls visibility, and runtime detection handles interactivity and state-change warnings.