# Understanding the Metadata Format for Omarchy Commands: A Complete Guide > Learn the Omarchy metadata format for CLI commands. This guide details group, name, summary, arguments, and more, embedded in executable files. - Repository: [Omacom/omarchy](https://github.com/omacom/omarchy) - Tags: deep-dive - Published: 2026-08-30 --- **Omarchy commands use an optional comment-header inside the first 80 lines of executable files under `bin/omarchy-*` to define CLI metadata including group, name, summary, arguments, examples, aliases, and visibility flags.** The Omarchy framework discovers commands by scanning executables placed in the `bin/` directory that match the `omarchy-*` naming pattern. According to the `omaccom/omarchy` source code, each command can declare its metadata format for Omarchy commands through a structured comment block that drives the router's help generation, route registration, and privilege checking. ## Where Metadata Is Defined Metadata is declared directly in the command source file and parsed by the central router script. The router (`bin/omarchy`) reads the first 80 lines of every `bin/omarchy-*` executable looking for lines starting with `# omarchy:`. Scanning stops at the first non-comment line (lines 39-42 of [`docs/cli-router.md`](https://github.com/omacom/omarchy/blob/main/docs/cli-router.md)), ensuring the metadata overhead remains minimal during startup. The canonical reference for supported keys lives in [`agents/skills/command-metadata.md`](https://github.com/omacom/omarchy/blob/main/agents/skills/command-metadata.md), while the parsing logic and route-building algorithm are documented in [`docs/cli-router.md`](https://github.com/omacom/omarchy/blob/main/docs/cli-router.md). ## Supported Metadata Keys and Syntax The metadata format for Omarchy commands supports eight distinct keys that override filename-based defaults or add descriptive context. ### Group and Name Overrides By default, the router splits the filename at the first hyphen to derive the group and name (e.g., `omarchy-theme-set` becomes group `theme`, name `set`). Metadata can override this: - **`# omarchy:group=`** – Assigns the command to a logical category (e.g., `# omarchy:group=backup`). - **`# omarchy:name=`** – Sets the command identifier (e.g., `# omarchy:name=restore`). ### Documentation Fields These keys populate the help system and command listings: - **`# omarchy:summary=`** – A single-sentence description displayed in `omarchy commands` output and help panels. The test suite in `test/cli` enforces the presence of this key when running `omarchy commands --check`. - **`# omarchy:args=`** – Defines the usage pattern. Required arguments appear outside square brackets; optional arguments sit inside (e.g., `# omarchy:args=[smart|region|windows|fullscreen] [slurp|copy]`). - **`# omarchy:examples=`** – Pipe-separated command examples shown in help text (e.g., `# omarchy:examples=omarchy screenshot | omarchy capture screenshot region`). ### Routing and Visibility Modifiers These keys control how the command appears in the CLI: - **`# omarchy:alias=`** or **`# omarchy:aliases=`** – Registers alternate routes pointing to the same binary. The router flags these as aliases in help listings. - **`# omarchy:hidden=true`** – Excludes the command from default `omarchy commands` listings while keeping it callable. - **`# omarchy:requires-sudo=true`** – Marks the command as requiring elevated privileges, allowing the router to surface warnings before execution. Malformed keys or values are silently ignored, causing the command to fall back to filename-derived routing. ## How the Router Processes Metadata The CLI router builds its dispatch table using a two-phase approach documented in [`docs/cli-router.md`](https://github.com/omacom/omarchy/blob/main/docs/cli-router.md). **Phase 1: Fast Path** The router first checks for an executable matching the full argument list literally. This bypasses metadata loading entirely for direct filename matches (lines 49-65 of [`cli-router.md`](https://github.com/omacom/omarchy/blob/main/cli-router.md)). **Phase 2: Metadata Assembly** When the fast path fails, the router: 1. Splits the filename `omarchy--` at hyphens to generate default routes. 2. Parses the comment header for `omarchy:` directives. 3. Constructs the **canonical route** (`omarchy `) using metadata overrides or filename defaults. 4. Registers **filename routes** (hyphens converted to spaces) as fallbacks. 5. Expands **aliases** into additional routes pointing to the same binary. 6. Applies **visibility filters** based on `hidden=true`. ## Practical Code Examples Below are production-ready patterns from the Omarchy repository demonstrating the metadata format for Omarchy commands. ### Standard Command with Arguments ```bash #!/bin/bash # bin/omarchy-screenshot # omarchy:summary=Take a screenshot # omarchy:args=[smart|region|windows|fullscreen] [slurp|copy] # omarchy:examples=omarchy screenshot | omarchy capture screenshot region # Command implementation follows... ``` ### Hidden Administrative Command ```bash #!/bin/bash # bin/omarchy-apply-hardware # omarchy:hidden=true # omarchy:requires-sudo=true # omarchy:summary=Apply hardware-specific configuration # Privileged hardware detection logic... ``` ### Command with Aliases ```bash #!/bin/bash # bin/omarchy-install-gaming-xbox-cloud # omarchy:name=gaming xbox-cloud # omarchy:alias=xbcloud # omarchy:summary=Install Xbox Cloud Gaming # Installation script... ``` ## Validation and Testing The Omarchy project enforces metadata quality through the test suite located in `test/cli`. Running `omarchy commands --check` validates that every command includes an explicit `# omarchy:summary=` and confirms that boolean flags like `hidden` and `requires-sudo` contain valid `true`/`false` values. ## Summary - Omarchy commands declare metadata in comment headers within the first 80 lines of `bin/omarchy-*` files. - Eight keys control grouping (`group`), naming (`name`), documentation (`summary`, `args`, `examples`), routing (`alias`/`aliases`), and visibility (`hidden`, `requires-sudo`). - The router (`bin/omarchy`) uses a fast-path check before falling back to full metadata parsing to build its route table. - Reference documentation lives in [`agents/skills/command-metadata.md`](https://github.com/omacom/omarchy/blob/main/agents/skills/command-metadata.md) and [`docs/cli-router.md`](https://github.com/omacom/omarchy/blob/main/docs/cli-router.md). - The `test/cli` suite enforces mandatory summary fields and boolean validation. ## Frequently Asked Questions ### What happens if I place metadata after the first 80 lines of a command? The router stops scanning at line 80 or the first non-comment line, whichever comes first. Any `# omarchy:` directives appearing after code begins are ignored by the parser. ### Can I use multiple aliases for a single Omarchy command? Yes. You can declare multiple alias keys using either `# omarchy:alias=` or the plural form `# omarchy:aliases=`. Each alias registers an independent route that resolves to the same executable binary. ### How does Omarchy handle conflicting metadata between the filename and header directives? Header directives take precedence over filename parsing. If `bin/omarchy-theme-set` contains `# omarchy:group=appearance` and `# omarchy:name=activate`, the canonical route becomes `omarchy appearance activate` rather than the default `omarchy theme set`. ### Are metadata keys case-sensitive? Yes. The router expects lowercase keys exactly as documented: `# omarchy:summary=`, `# omarchy:hidden=true`, etc. Malformed or miscapitalized keys are treated as regular comments and ignored during route construction.