# How Omarchy Commands Define Metadata: The Complete Guide to # omarchy: Comments > Learn how Omarchy commands define metadata using special # omarchy comments. Discover how this metadata generates help text, validates arguments, and organizes menus in this comprehensive guide. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: deep-dive - Published: 2026-08-25 --- **Omarchy commands embed descriptive metadata directly in script files using special `# omarchy:` comment prefixes, which the main `bin/omarchy` router parses to generate help text, argument validation, and menu organization.** The **basecamp/omarchy** repository implements a self-documenting CLI framework where each command script carries its own specification. This design eliminates external configuration files by storing **Omarchy command metadata** in structured comment headers that the router extracts at runtime. ## The # omarchy: Comment Convention Every Omarchy command script begins with a block of comments starting with `# omarchy:`. These lines follow a strict `key=value` syntax that declares everything from user-facing descriptions to runtime requirements. ### Core Metadata Keys The parser recognizes several standard keys that control command behavior and visibility: - **summary** – A one-sentence description displayed in command listings. Example: `# omarchy:summary=Install, launch, stop, inspect, or remove the Windows VM` - **args** – Argument syntax hints shown in help output. Example: `# omarchy:args= [options]` - **requires-sudo** – Boolean flag indicating elevated privileges are required. Example: `# omarchy:requires-sudo=true` - **hidden** – When set to `true`, excludes the command from public menus. Example: `# omarchy:hidden=true` - **group** – Logical grouping for menu organization (e.g., `transcode`, `webapp`). Example: `# omarchy:group=transcode` - **name** – Explicit sub-command name when a single file implements multiple verbs. Example: `# omarchy:name=ascii` - **examples** – Usage examples appearing in help documentation. Example: `# omarchy:examples=omarchy transcode ascii ~/logo.svg /tmp/logo.txt` ## How the bin/omarchy Router Parses Metadata The metadata extraction logic lives in **`bin/omarchy`**, specifically within the initialization routines that build the command registry. The router performs four distinct operations when loading commands: 1. **Directory Traversal** – The script locates executable files matching the `omarchy--` naming convention within the `bin/` directory. 2. **Comment Block Extraction** – For each command file, the parser reads lines sequentially until encountering a non-comment line, capturing any line matching the `^#\ omarchy:(.+)=(.+)$` pattern. 3. **Associative Array Population** – Extracted key-value pairs populate namespaced associative arrays using dynamic variable naming (e.g., `CMD_SUMMARY`, `CMD_ARGS`, `CMD_HIDDEN`). 4. **Group Description Integration** – The `GROUP_DESCRIPTIONS` associative array, defined at [line 27 in `bin/omarchy`](https://github.com/basecamp/omarchy/blob/quattro/bin/omarchy#L27), maps group identifiers to human-readable menu headings. The parsing implementation uses Bash regex matching to isolate keys and values: ```bash # Excerpt from bin/omarchy showing metadata extraction while IFS= read -r line; do [[ $line =~ ^#\ omarchy:(.+)=(.+)$ ]] && { key=${BASH_REMATCH[1]} val=${BASH_REMATCH[2]} declare -g "CMD_${key^^}[$cmd]=$val" } done < <(head -n 20 "$cmd_path") ``` ## Real-World Command Metadata Example The **`bin/omarchy-windows-vm`** command demonstrates a complete metadata block at the beginning of the script: ```bash #!/usr/bin/env bash # omarchy:summary=Manage the Windows development VM # omarchy:args= [--memory=8G] # omarchy:requires-sudo=true # omarchy:group=vm omarchy-windows-vm() { # Command implementation follows metadata case "$1" in install) install_vm "$2" ;; # ... esac } ``` Similarly, **`bin/omarchy-transcode`** utilizes advanced keys for sub-command routing and grouping: ```bash #!/usr/bin/env bash # omarchy:summary=Convert media files to different formats # omarchy:args= [--format=mp4] # omarchy:group=media # omarchy:name=transcode # omarchy:examples=omarchy transcode input.avi output.mp4 omarchy-transcode() { ffmpeg -i "$1" "$3" "$2" } ``` These examples illustrate how **Omarchy command metadata** remains co-located with implementation logic, ensuring documentation stays synchronized with code changes. ## Summary - Omarchy uses **`# omarchy:`** comment prefixes to embed metadata directly in command scripts, eliminating separate configuration files. - The **`bin/omarchy`** router parses these comments into associative arrays to generate help text, validate arguments, and organize menu groups. - Supported keys include **summary**, **args**, **requires-sudo**, **hidden**, **group**, **name**, and **examples**. - The `GROUP_DESCRIPTIONS` array at line 27 of the main router defines human-readable headings for command groups. - Commands following the `omarchy--` naming convention are automatically discovered and cataloged based on their metadata headers. ## Frequently Asked Questions ### What is the exact syntax for Omarchy metadata comments? Each metadata line must begin with `# omarchy:` followed immediately by a key, an equals sign, and a value with no spaces around the equals sign. For example: `# omarchy:summary=Manage virtual machines`. The parser uses the regex pattern `^#\ omarchy:(.+)=(.+)$`, so keys and values cannot contain unescaped equals signs or omit the prefix. ### How does Omarchy handle commands that require root privileges? When a command script includes `# omarchy:requires-sudo=true`, the `bin/omarchy` router checks the effective UID before executing the command function. If the user lacks superuser privileges, the router emits a permission error and exits before invoking the command implementation, providing a consistent security boundary across the CLI. ### Where is the metadata parser implemented in the source code? The extraction logic resides in **`bin/omarchy`** within the command discovery loop. The `GROUP_DESCRIPTIONS` associative array initializes at [line 27](https://github.com/basecamp/omarchy/blob/quattro/bin/omarchy#L27), while the regex-based parsing routine appears shortly after in the same file. This centralized parsing ensures all Omarchy commands receive uniform metadata processing regardless of their specific group or function. ### Can a single Omarchy script define multiple sub-commands? Yes. When a script implements multiple related verbs (such as `omarchy-transcode` handling both `ascii` and `video` conversions), use the `# omarchy:name=` key to declare distinct identities. The router treats each unique name value as a separate entry in the command registry, allowing one physical file to register multiple logical commands with independent metadata blocks.