Understanding Omarchy Command Metadata Comments: A Complete Guide

Omarchy command metadata comments are specially-formatted comment lines beginning with # omarchy: that embed documentation, routing hints, and privilege requirements directly in executable scripts under bin/, enabling automatic help generation and command discovery.

In the basecamp/omarchy repository, command metadata comments provide a declarative way for executables to describe their behavior without external configuration files. These comments allow the central router (bin/omarchy) and documentation tools to extract structured information directly from source code, powering help text, command-line completion, and menu organization.

Supported Metadata Keys

The Omarchy router recognizes eight distinct metadata keys. Each uses the format # omarchy:key=value and controls specific aspects of command routing and documentation.

• # omarchy:group=… — Overrides the command group inferred from the filename. Use this to place commands under logical categories such as capture, theme, or network.

• # omarchy:name=… — Overrides the command name inferred from the filename. This enables multi-word command names (e.g., gaming xbox-cloud) or backward-compatible renaming.

• # omarchy:summary=… — Provides a short, one-sentence description displayed in help listings. This text appears when users run omarchy <command> --help.

• # omarchy:args=… — Supplies a formal description of expected arguments for usage strings, such as <install|remove|launch> [options].

• # omarchy:examples=… — Lists concrete usage examples separated by the pipe character |. These demonstrate typical invocations when argument syntax requires explanation.

• # omarchy:alias=… and # omarchy:aliases=… — Define alternate routes that map to the same command implementation, providing shorthand or backward-compatible entry points.

• # omarchy:hidden=true — Excludes the command from default listings. Use this for internal utilities or deprecated commands that should not appear in help output.

• # omarchy:requires-sudo=true — Marks the command as requiring elevated privileges. The router uses this to warn users or automatically prepend sudo or pkexec when appropriate.

Placement and Parsing Constraints

According to docs/cli-router.md, the metadata parser scans only the first 80 lines of each script. Comments appearing after this boundary are ignored. Malformed or unknown keys are silently discarded, ensuring that only recognized metadata affects routing behavior.

Code Examples from the Repository

The following examples demonstrate how real Omarchy commands implement these metadata comments.

Basic metadata in bin/omarchy-windows-vm:

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

Complex usage with examples:

# omarchy:summary=Take a screenshot

# omarchy:args=[smart|region|windows|fullscreen] [slurp|copy]

# omarchy:examples=omarchy screenshot | omarchy capture screenshot region

Custom grouping and naming:

# omarchy:group=capture

# omarchy:name=screenrecord

# omarchy:summary=Record a video of the screen

# omarchy:args=[duration] [output]

Key Implementation Files

Three files define and consume Omarchy command metadata comments:

• agents/skills/command-metadata.md — The authoritative specification listing every supported key and coding conventions.
• bin/omarchy-windows-vm — A concrete implementation demonstrating summary, args, and requires-sudo fields.
• docs/cli-router.md — Documentation explaining how the router parses metadata, handles groups, and respects hidden flags.

Summary

• Omarchy command metadata comments use the # omarchy:key=value format to embed documentation directly in executable scripts.

• The router parses the first 80 lines of files in bin/ to extract grouping, naming, argument syntax, and privilege requirements.

• Eight keys control visibility (hidden), grouping (group), naming (name, alias), documentation (summary, args, examples), and privilege escalation (requires-sudo).

• Malformed or unknown keys are ignored, ensuring robust backward compatibility.

• Real-world usage in bin/omarchy-windows-vm demonstrates declarative command configuration without external metadata files.

Frequently Asked Questions

What file format do Omarchy metadata comments use?

Omarchy metadata comments are shell-style line comments beginning with # omarchy: followed by a key-value pair in the format key=value. These must appear within the first 80 lines of the script to be recognized by the router according to docs/cli-router.md.

Can I use multiple metadata keys in a single command file?

Yes. A command can include multiple metadata comments, each on its own line. For example, you can combine # omarchy:group=capture, # omarchy:name=screenshot, and # omarchy:summary=Take a screen capture in the same file to define categorization, naming, and help text simultaneously.

How does the requires-sudo metadata affect command execution?

When # omarchy:requires-sudo=true is present, the central router (bin/omarchy) detects the privilege requirement before executing the command. The system can then warn the user or automatically prepend sudo/pkexec to the invocation, ensuring the command runs with appropriate elevated permissions.

Why would a command use the hidden=true metadata?

The hidden=true flag removes a command from default help listings and menu systems while keeping the executable functional. This is useful for internal utilities, deprecated commands maintained for backward compatibility, or advanced tools intended only for power users who know the specific command name.

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