# Supported Metadata Keys in Omarchy Command Headers > Discover supported metadata keys in Omarchy command headers like summary, args, and alias. Omarchy uses these keys to generate help output, enforce permissions, and route commands. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: api-reference - Published: 2026-08-27 --- **Omarchy command headers support eight metadata keys—`summary`, `args`, `requires-sudo`, `hidden`, `examples`, `group`, `name`, and `alias`—that the `bin/omarchy` router extracts from the first 80 lines of executable scripts to generate help output, enforce permissions, and route aliases.** Omarchy, the opinionated Linux distribution maintained by Basecamp, embeds command metadata directly within executable comments rather than external configuration files. These declarative headers, documented in [`agents/skills/command-metadata.md`](https://github.com/basecamp/omarchy/blob/main/agents/skills/command-metadata.md), allow the CLI dispatcher to introspect capabilities, generate bash completions, and validate sudo requirements without executing the underlying code. ## Supported Metadata Keys The parser scans for lines matching the pattern `# omarchy:key=value` within the first 80 lines of any command file. According to the basecamp/omarchy source code, the router recognizes the following keys: ### summary Provides the human-readable description displayed in help listings and command indexes. ```bash # omarchy:summary=Install, launch, stop, inspect, or remove the Windows VM ``` ### args Documents the command-line arguments for usage displays and shell completion generation. This value is consumed by `default/bash/completions` to provide tab-completion hints. ```bash # omarchy:args= [options] ``` ### requires-sudo Accepts `true` or `false` to indicate whether the command must execute with elevated privileges. The dispatcher checks this flag before invoking the script. ```bash # omarchy:requires-sudo=true ``` ### hidden When set to `true`, excludes the command from auto-generated help menus while keeping it fully routable. Useful for internal utilities or beta features. ```bash # omarchy:hidden=true ``` ### examples One or more concrete usage samples separated by pipes (`|`). These appear in help output to demonstrate valid invocations. ```bash # omarchy:examples=omarchy upgrade to quattro | omarchy upgrade to quattro --dev ``` ### group Categorizes the command under a specific heading in the top-level help menu, organizing related utilities logically. ```bash # omarchy:group=backup ``` ### name Explicitly overrides the command name derived from the filename. This is essential for creating virtual commands or when the script filename differs from the desired invocation name. ```bash # omarchy:name=test ``` ### alias Declares alternate names that route to the same command implementation. Multiple aliases can be defined to provide backward compatibility or shorthand variants. ```bash # omarchy:alias=omarchy parenthelp-alias ``` ## Implementation and Parsing Behavior The metadata extraction logic resides in the CLI router (`bin/omarchy`) and is strictly enforced by the test suite in `test/cli`. The implementation behavior follows these rules: - **Line limit**: Only the first 80 lines of a script are scanned for metadata headers. - **Case sensitivity**: Keys must be lowercase and hyphenated exactly as documented in [`agents/skills/command-metadata.md`](https://github.com/basecamp/omarchy/blob/main/agents/skills/command-metadata.md). - **Value format**: Values are treated as literal strings; boolean keys accept `true` or `false` string values. - **Routing priority**: The `name` key takes precedence over the filename when determining how the command is invoked. ## Removed and Ignored Keys The parser deliberately ignores several deprecated keys that previously appeared in early drafts. The test suite explicitly verifies that these legacy fields are absent: - `legacy` - `usage` - `visibility` - `mutates` - `interactive` These keys are parsed but discarded, ensuring backward compatibility without affecting router behavior. ## Practical Code Examples Below are complete header sections demonstrating valid metadata configurations. **Standard visible command with full documentation:** ```bash #!/usr/bin/env bash # omarchy:summary=Manage Windows virtual machines # omarchy:args= # omarchy:requires-sudo=true # omarchy:group=vm # omarchy:name=windows-vm # omarchy:alias=vm # omarchy:examples=omarchy windows-vm install | omarchy windows-vm status ``` **Hidden administrative utility:** ```bash #!/usr/bin/env bash # omarchy:summary=Internal cleanup routine # omarchy:hidden=true # omarchy:requires-sudo=false ``` **Simple aliased command:** ```bash #!/usr/bin/env bash # omarchy:summary=Display system backup status # omarchy:group=backup # omarchy:name=backup-status # omarchy:alias=status ``` ## Summary - Omarchy recognizes **eight supported metadata keys**: `summary`, `args`, `requires-sudo`, `hidden`, `examples`, `group`, `name`, and `alias`. - Headers must appear within the **first 80 lines** of the script and follow the `# omarchy:key=value` syntax. - The schema is formally defined in [`agents/skills/command-metadata.md`](https://github.com/basecamp/omarchy/blob/main/agents/skills/command-metadata.md) and enforced by the test suite in `test/cli`. - Deprecated keys including `visibility`, `mutates`, and `interactive` are explicitly ignored by the parser. - The `args` key drives shell completion logic located in `default/bash/completions`. ## Frequently Asked Questions ### What is the exact syntax for Omarchy command metadata headers? Metadata headers must begin with `# omarchy:` followed immediately by the key name, an equals sign, and the value. No spaces are permitted around the equals sign. The router scans the first 80 lines of the executable file for these patterns, as implemented in the `bin/omarchy` dispatcher. ### Which metadata keys are deprecated or ignored by the Omarchy router? The parser ignores the legacy keys `usage`, `visibility`, `mutates`, `interactive`, and `legacy`. The test suite in `test/cli` explicitly validates that these fields do not influence command behavior, ensuring they can remain in scripts for documentation purposes without affecting runtime logic. ### How does the Omarchy CLI use the `args` metadata key? The `args` value is extracted by the router to generate usage strings in help output and to provide completion hints via the scripts in `default/bash/completions`. It documents the expected positional arguments and options without enforcing them at the parser level. ### Can a command have multiple aliases using the metadata system? While the `alias` key accepts a single value, you can define multiple routing entries by creating separate wrapper scripts that share the same implementation or by using the `alias` key to point to a primary command name. The `name` key overrides the filename, allowing flexible routing configurations.