# Understanding Metadata Comments in Omarchy Commands: A Complete Guide > Master Omarchy metadata comments. Learn how these annotations override routing, define groups, set descriptions, and control visibility to enhance your command line tools. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: how-to-guide - Published: 2026-08-26 --- **Metadata comments in Omarchy commands are declarative annotations placed at the top of executable files that override filename-based routing, define command groups, set descriptions, and control visibility and permissions.** Omarchy treats every script matching `bin/omarchy-*` as a potential CLI command. While the framework infers command structure from filenames by default, metadata comments provide a declarative mechanism to customize routing, documentation, and execution behavior without renaming files. These annotations are processed by the router defined in [`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md) and documented in [`agents/skills/command-metadata.md`](https://github.com/basecamp/omarchy/blob/main/agents/skills/command-metadata.md). ## How Metadata Comments Define Command Routing ### Overriding Filename-Based Inference By default, Omarchy parses the filename after the `omarchy-` prefix and splits at the first hyphen to determine the command group and name. Metadata comments override this behavior using specific directives. For example, a file named `bin/omarchy-install-gaming-xbox-cloud` can be remapped to respond to `omarchy gaming xbox-cloud` using: ```bash #!/usr/bin/env bash # omarchy:group=gaming # omarchy:name=xbox-cloud # omarchy:summary=Install Xbox Cloud Gaming client ``` The command remains callable at both the canonical metadata route (`omarchy gaming xbox-cloud`) and the original filename route (`omarchy install gaming xbox cloud`). ### Declaring Root Group Commands Setting `# omarchy:name=` with an empty value designates the command as the root entry point for its specified group. This makes the command callable via `omarchy group-name` without requiring a subcommand. ## Essential Metadata Keys for Omarchy Commands ### Command Identification and Routing - **`# omarchy:group=…`** — Forces the command into a specific category, replacing the group derived from the filename. - **`# omarchy:name=…`** — Sets the canonical command name; an empty value creates a root group command. - **`# omarchy:alias=…`** and **`# omarchy:aliases=…`** — Register alternate routes that resolve to the same binary. The router flags these as aliases in `omarchy commands` listings. ### Documentation and Help Generation - **`# omarchy:summary=…`** — Supplies the short description shown in `omarchy commands` listings and automatically generated help pages. A concrete example appears in `bin/omarchy-theme-list`. - **`# omarchy:args=…`** — Defines expected arguments. If a command declares required arguments and none are supplied, the router displays help instead of executing. - **`# omarchy:examples=…`** — Provides usage examples that appear in the help output. ### Security and Visibility Controls - **`# omarchy:hidden=true`** — Keeps the command callable but removes it from the default `omarchy commands` listing. This pattern is used for internal plumbing that users should not discover by browsing, such as `omarchy-apply-hardware`. - **`# omarchy:requires-sudo=true`** — Marks the command as needing elevated privileges; the router can warn or enforce sudo when the command is invoked. ## How the Router Parses Metadata Comments ### The 80-Line Parsing Limit According to [`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md), the router reads metadata comments exclusively from the **first 80 lines** of the file, stopping immediately at the first non-comment line. Anything after that boundary is ignored for routing purposes. ### Fast Path vs. Metadata Resolution The Omarchy router implements a two-phase resolution strategy: 1. **Fast Path**: The router builds a hyphen-joined candidate from supplied arguments and checks for a matching executable directly. 2. **Metadata Resolution**: If the fast path fails (because metadata moved the command's route), the router loads **all** metadata tables and resolves routes using a longest-prefix match. Malformed or unknown metadata keys are silently ignored, causing the command to fall back to its filename-derived route rather than breaking the router. ### Hidden Command Dispatch Commands marked as hidden still register and dispatch normally; they are merely omitted from the default `omarchy commands` listing. Internal scripts can continue to invoke hidden commands directly without restrictions. ## Practical Implementation Examples Complete metadata declaration for a screenshot utility: ```bash #!/usr/bin/env bash # omarchy:summary=Take a screenshot # omarchy:args=[smart|region|windows|fullscreen] [slurp|copy] # omarchy:examples=omarchy screenshot | omarchy capture screenshot region # omarchy:requires-sudo=true ``` Hiding internal plumbing: ```bash #!/usr/bin/env bash # omarchy:hidden=true # omarchy:summary=Internal apply-hardware plumbing ``` Reading metadata programmatically (as implemented in the router): ```bash header=$(head -n 80 "$command_path") summary=$(grep -m1 '^# omarchy:summary=' <<<"$header" | cut -d= -f2-) ``` ## Summary - Metadata comments use the `# omarchy:key=value` syntax and must appear within the first 80 lines of executable files under `bin/omarchy-*`. - The **`group`** and **`name`** keys override filename-based routing, while an empty **`name`** value creates a root group command. - Documentation keys (**`summary`**, **`args`**, **`examples`**) populate help output automatically based on [`agents/skills/command-metadata.md`](https://github.com/basecamp/omarchy/blob/main/agents/skills/command-metadata.md) specifications. - **`hidden=true`** conceals internal plumbing commands from discovery without disabling execution or dispatch. - **`requires-sudo=true`** flags privilege requirements for pre-execution safety checks. - The router uses a fast-path filename check first, falling back to metadata table resolution with longest-prefix matching only when necessary. ## Frequently Asked Questions ### Where should metadata comments be placed in an Omarchy command file? Metadata comments must appear at the top of the file, within the first 80 lines and before any executable code. The parser stops reading metadata at the first non-comment line, so all directives should immediately follow the shebang or precede any shell commands. ### What happens if I use an invalid metadata key in an Omarchy command? Malformed or unknown metadata keys are silently ignored according to the router implementation in [`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md). The command continues to function using its filename-derived route rather than failing, ensuring backward compatibility and system resilience. ### Can hidden Omarchy commands still be executed directly? Yes. Commands marked with `# omarchy:hidden=true` remain fully callable via their routing paths and function normally when invoked by scripts or directly by name. The hidden flag only removes the command from the default `omarchy commands` listing to prevent user discovery of internal utilities. ### How does the Omarchy router handle command aliases? The router processes `# omarchy:alias=…` or `# omarchy:aliases=…` entries to register alternate routes that resolve to the same binary. These aliases participate in the longest-prefix matching resolution algorithm alongside primary routes and are flagged appropriately in command listings.