# Understanding Omarchy Command Metadata Comments: A Complete Guide > Discover Omarchy command metadata comments. Learn how these `# omarchy:` comments in your scripts document commands, define routing, and set privileges for automatic help generation. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: deep-dive - Published: 2026-08-22 --- **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 --help`. - **# omarchy:args=…** — Supplies a formal description of expected arguments for usage strings, such as ` [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`](https://github.com/basecamp/omarchy/blob/main/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`: ```bash #!/bin/bash # omarchy:summary=Install, launch, stop, inspect, or remove the Windows VM # omarchy:args= [options] # omarchy:requires-sudo=true ``` Complex usage with examples: ```bash # 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: ```bash # 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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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.