Omarchy Command Metadata: Complete Guide to Available Fields and Usage

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

#!/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

#!/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

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

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