# How Omarchy Parses Command Metadata: Understanding `#omarchy:summary` and `#omarchy:hidden` > Learn how Omarchy parses command metadata like #omarchy:summary and #omarchy:hidden. Discover how it controls visibility documentation and behavior by scanning script comments. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: internals - Published: 2026-08-19 --- **The Omarchy CLI router treats executable scripts as self-describing binaries by scanning the first 80 lines for comments matching `# omarchy:key=value`, parsing them into an associative array that controls command visibility, documentation, and behavior.** Omarchy, the declarative Linux workstation framework from Basecamp, implements a self-documenting CLI architecture where command scripts carry their own metadata. The router located at `bin/omarchy` extracts configuration directly from script headers to build help menus, handle argument completion, and filter hidden commands without relying on external manifest files. Understanding this parsing mechanism allows developers to properly annotate custom commands for the Omarchy ecosystem. ## How the Router Scans Command Scripts When the Omarchy router initializes, it walks the `bin/` directory and inspects every executable file to discover available commands. Rather than parsing entire files, the system samples only the header region to maximize startup performance. For each file `cmd_path`, the router executes `head -n 80 "$cmd_path"` and pipes the result into a Bash `while read -r line` loop. This 80-line limit ensures rapid CLI initialization while accommodating substantial metadata blocks. Lines beyond this boundary are ignored entirely, even if they contain valid `# omarchy:` directives. ## The Parsing Algorithm Step-by-Step The extraction logic follows a precise sequence defined in the first 80 lines of `bin/omarchy`. Each line undergoes validation and transformation before populating the command's metadata registry. 1. **Header capture**: The router retrieves the first 80 lines using the `head` command. 2. **Pattern validation**: Each line is tested against the regex `^# omarchy:([A-Za-z_-]+)=(.*)$`. Malformed lines are silently discarded. 3. **Key isolation**: Capture group 1 yields the metadata key (e.g., `summary`, `hidden`, `requires-sudo`). 4. **Value extraction**: Capture group 2 contains the raw value string. 5. **Key normalization**: Keys are lower-cased and hyphens converted to underscores, transforming `requires-sudo` into `requires_sudo`. 6. **Type coercion**: Values matching the literal strings `true` or `false` convert to Bash booleans; all other values are whitespace-trimmed and stored as literal strings. 7. **Array population**: Parsed pairs populate an associative array named `meta` (e.g., `meta[summary]`, `meta[hidden]`). 8. **Default fallback**: Missing keys inherit inferred values, such as the filename for command names or empty strings for optional fields like `summary`. ## Populating Help Documentation with `#omarchy:summary` The `summary` metadata key provides the human-readable description displayed in `omarchy help` output and shell completion menus. When populated, `meta[summary]` overrides any auto-generated description, giving command authors precise control over user-facing documentation. To add a summary to a custom command, include a comment line following the exact format: ```bash #!/usr/bin/env bash # omarchy:summary=Take a screenshot of the selected region # omarchy:args=[smart|region|window|fullscreen] # omarchy:examples=omarchy screenshot region | omarchy screenshot fullscreen # Implementation follows... ``` According to the source code in `bin/omarchy`, these summaries feed directly into the `GROUP_DESCRIPTIONS` array that powers the interactive help system. The completion scripts located in `default/bash/completions` also reference this value when providing argument hints to the user. ## Hiding Commands with `#omarchy:hidden` Commands marked with `# omarchy:hidden=true` remain fully functional but disappear from default listings and help menus. The router checks `meta[hidden]` when assembling the command table, executing `continue` to skip entries where the value equals boolean `true`. This mechanism suits utility scripts, internal debugging tools, or deprecated commands that must remain accessible without cluttering the primary interface. The command remains callable by its explicit name because the router still registers the binary path; only the listing behavior changes. Implementation requires a single metadata line: ```bash #!/usr/bin/env bash # omarchy:summary=Internal debug utility for developers # omarchy:hidden=true # Debug implementation... ``` Even though this command executes normally when invoked directly (e.g., `omarchy debug-helper`), it will **not** appear in `omarchy help` or the auto-generated command table. ## Advanced Metadata Configuration Beyond basic visibility and descriptions, the parser supports additional keys documented in [`agents/skills/command-metadata.md`](https://github.com/basecamp/omarchy/blob/main/agents/skills/command-metadata.md). The `requires-sudo` key automatically adds privilege escalation hints to help output, while `name` and `group` override the default command categorization derived from filename prefixes. A complete example demonstrating multiple metadata fields: ```bash #!/usr/bin/env bash # omarchy:name=system-reboot # omarchy:group=system # omarchy:summary=Reboot the machine safely # omarchy:requires-sudo=true # omarchy:hidden=false # Reboot logic... ``` In this case, the router registers the command as `system-reboot` within the `system` group, displays the summary with a sudo warning, and includes it in standard listings. The parser normalizes `requires-sudo` to `requires_sudo` in the `meta` array, which the help generator checks to display privilege requirements. ## Summary - The Omarchy router scans the first 80 lines of each executable in `bin/` to extract metadata comments using `head -n 80`. - Comments must match the regex `^# omarchy:([A-Za-z_-]+)=(.*)$` to be recognized by the parser. - Parsed values populate the `meta` associative array, with keys normalized to lowercase and underscores. - The `summary` key drives help documentation and completion descriptions shown to users. - The `hidden` key filters commands from listings while preserving executability via direct invocation. - Boolean strings (`true`/`false`) convert automatically during parsing; other values remain literal strings. - All parsing logic resides in `bin/omarchy`, with key specifications documented in [`agents/skills/command-metadata.md`](https://github.com/basecamp/omarchy/blob/main/agents/skills/command-metadata.md). ## Frequently Asked Questions ### How many lines does the Omarchy router scan for metadata? The router examines only the first 80 lines of each executable script using `head -n 80`. This constraint balances comprehensive metadata support with startup performance, ensuring the CLI remains responsive even when numerous custom commands are present. ### Can I use custom metadata keys beyond the standard set? While the router accepts any key matching the `# omarchy:key=value` pattern and stores it in the `meta` associative array, only documented keys in [`agents/skills/command-metadata.md`](https://github.com/basecamp/omarchy/blob/main/agents/skills/command-metadata.md) affect built-in router behavior. Custom keys are accessible to your scripts but will not alter the command listing, help output, or completion generation unless you modify the router itself. ### What happens if a metadata line is malformed? Lines that do not match the regex `^# omarchy:([A-Za-z_-]+)=(.*)$` are silently ignored during parsing. This includes comments with misspelled prefixes (e.g., `# omachy:...`), missing equals signs, or invalid characters in the key name. The router continues processing subsequent lines without throwing errors. ### Where is the metadata parsing logic located in the source code? The complete parsing implementation resides in the router script `bin/omarchy`, specifically within the first 80 lines where the "Command metadata" section handles the `head` extraction, regex matching, and associative array population. The supported keys and their semantics are documented in [`agents/skills/command-metadata.md`](https://github.com/basecamp/omarchy/blob/main/agents/skills/command-metadata.md).