# Omarchy CLI Commands Metadata Keys: Complete Reference Guide > Explore Omarchy CLI commands and their metadata keys. Discover how group name summary args examples alias hidden and requires sudo control routing documentation and visibility for your scripts. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: api-reference - Published: 2026-08-29 --- **Omarchy CLI commands support eight distinct metadata keys—`group`, `name`, `summary`, `args`, `examples`, `alias`/`aliases`, `hidden`, and `requires-sudo`—that are extracted from comment lines near the top of executable scripts to control routing, documentation, and visibility.** The Omarchy framework by Basecamp uses a declarative metadata system to define CLI behavior directly within bash scripts located in the `bin/` directory. Understanding the supported metadata keys for Omarchy CLI commands is essential for extending the toolchain, as these declarations determine how commands are categorized, named, and presented to users without modifying the central router logic. ## How Omarchy Parses Command Metadata When the Omarchy router (`bin/omarchy`) initializes, it scans the first **80 lines** of every executable script in `bin/` to extract metadata declarations. The router looks for comments matching the strict pattern `# omarchy:=` and processes them within the `register_command` function. According to the basecamp/omarchy source code, a `case` block in `bin/omarchy` (lines 11–19) handles the parsing logic for each supported key, mapping valid metadata to internal command structures. ## Supported Metadata Keys The authoritative list of supported metadata keys is documented in [`agents/skills/command-metadata.md`](https://github.com/basecamp/omarchy/blob/main/agents/skills/command-metadata.md). Each key overrides default behaviors inferred from filenames or provides additional context for help generation. ### `group` – Override Command Grouping The `# omarchy:group=…` key overrides the command group that would otherwise be inferred from the filename. This allows scripts to organize logically under different namespaces regardless of their physical location. ### `name` – Override Command Name Use `# omarchy:name=…` to specify the sub-command name that appears after the group. This overrides the default name extraction from the filename, enabling cleaner or more descriptive command interfaces. ### `summary` – Define Help Text The `# omarchy:summary=…` key provides a short description that appears in command listings. This text is displayed when users run `omarchy --help` or list commands within a group. ### `args` – Document Usage Arguments Use `# omarchy:args=…` to describe positional or optional arguments using concise notation (e.g., `[smart|region]` or ``). This key populates the usage section of help output. ### `examples` – Provide Usage Examples The `# omarchy:examples=…` key accepts one or more example invocations separated by the pipe character `|`. Only use this when arguments require illustration, as it renders concrete usage patterns in help text. ### `alias` and `aliases` – Create Alternate Routes Both `# omarchy:alias=…` and `# omarchy:aliases=…` (plural form) provide alternate routes that map to the same command implementation. This allows multiple command names to trigger identical functionality without duplicating scripts. ### `hidden` – Suppress from Listings Setting `# omarchy:hidden=true` marks the command as hidden. Hidden commands are omitted from default command listings unless the user explicitly requests `--all`, making this ideal for deprecated or advanced utilities. ### `requires-sudo` – Flag Privilege Requirements The `# omarchy:requires-sudo=true` key flags commands that require elevated privileges. The value must be either omitted or explicitly set to `true`; when present, Omarchy can warn users or automatically escalate privileges before execution. ## Implementation in the Router The metadata extraction logic resides in `bin/omarchy`, specifically within the `register_command` function. As implemented in basecamp/omarchy, the router uses a `case` statement to process each metadata key, validating and assigning values to command properties. The [`agents/skills/command-metadata.md`](https://github.com/basecamp/omarchy/blob/main/agents/skills/command-metadata.md) file serves as the contract reference, ensuring consistency between the parser implementation and developer documentation. ## Practical Code Examples The following examples demonstrate complete metadata declarations in executable bash scripts: ```bash #!/usr/bin/env bash # omarchy:summary=Take a screenshot # omarchy:args=[smart|region|fullscreen] [slurp|copy] # omarchy:examples=omarchy screenshot | omarchy capture screenshot region # omarchy:alias=screenshot # omarchy:requires-sudo=true # omarchy:hidden=true # … implementation of the screenshot command … ``` ```bash #!/usr/bin/env bash # omarchy:group=theme # omarchy:name=set # omarchy:summary=Apply a theme # omarchy:args= # omarchy:examples=omarchy theme set SolarizedDark | omarchy theme set Nord # … implementation of the theme‑set command … ``` ## Summary - Omarchy extracts metadata from the first 80 lines of scripts in `bin/` using the pattern `# omarchy:=`. - Eight keys control command behavior: `group`, `name`, `summary`, `args`, `examples`, `alias`/`aliases`, `hidden`, and `requires-sudo`. - The `register_command` function in `bin/omarchy` processes these declarations using a case block (lines 11–19). - Reference documentation lives in [`agents/skills/command-metadata.md`](https://github.com/basecamp/omarchy/blob/main/agents/skills/command-metadata.md), defining the contract for all Omarchy CLI metadata. - Metadata allows scripts to override filename-derived defaults, provide usage examples, create aliases, and flag sudo requirements. ## Frequently Asked Questions ### What is the exact syntax for declaring metadata in Omarchy commands? Metadata declarations must follow the strict format `# omarchy:=` as comments near the top of executable scripts. The router only scans the first 80 lines of each file, and keys must match those handled in the `register_command` function's case block within `bin/omarchy`. ### Can a single Omarchy command have multiple aliases? Yes. Use either `# omarchy:alias=…` for a single alternate route or `# omarchy:aliases=…` when declaring multiple aliases. Both keys are processed by the same logic in the router, allowing multiple command paths to map to a single implementation. ### Where is the authoritative list of supported metadata keys documented? The definitive reference lives in [`agents/skills/command-metadata.md`](https://github.com/basecamp/omarchy/blob/main/agents/skills/command-metadata.md) within the basecamp/omarchy repository. This file serves as the contract between the router implementation (`bin/omarchy`) and command developers, detailing valid keys and their expected values. ### How does Omarchy handle commands that require elevated privileges? Commands requiring root access should declare `# omarchy:requires-sudo=true`. This metadata flag alerts the system that the command needs sudo privileges, allowing Omarchy to handle privilege escalation or display appropriate warnings before execution.