# Metadata Schema for Omarchy Commands: Complete CLI Routing Guide > Explore the Omarchy CLI metadata schema. Learn how Bash commands define routing permissions and documentation using # omarchy: comment directives. Your complete CLI routing guide. - Repository: [Omacom/omarchy](https://github.com/omacom/omarchy) - Tags: architecture - Published: 2026-09-04 --- **The Omarchy CLI uses a declarative metadata schema where Bash commands define routing, permissions, and documentation through specially formatted comment directives prefixed with `# omarchy:`.** This metadata schema powers the command-router in the `omacom/omarchy` repository, enabling automatic route generation, help text creation, and permission enforcement for the Omarchy dotfiles manager. Understanding this schema is essential for extending the CLI or troubleshooting routing issues. ## How the Metadata Schema Works Omarchy commands are executables stored in `bin/omarchy-*` files. When the router loads a command binary, it scans the first 80 lines (defined by `METADATA_SCAN_LIMIT`) for directives starting with `# omarchy:`. The router parses these directives using a regular expression at lines 202-236 of `bin/omarchy`: ```bash ^[[:space:]]*#[[:space:]]*omarchy:([[:alnum:]_-]+)=(.*)$ ``` Matched directives populate associative arrays that drive the CLI behavior: - `COMMAND_GROUP` – categorizes commands (e.g., `theme`, `update`) - `COMMAND_NAME` – the action name in the route - `COMMAND_SUMMARY` – description for help output - `COMMAND_ARGS` – argument placeholders - `COMMAND_EXAMPLES` – usage examples - `COMMAND_REQUIRES_SUDO` – privilege requirements - `COMMAND_HIDDEN` – visibility in listings - `COMMAND_ALIASES` – alternative routes If metadata is missing, the router applies fallback logic: the **group** defaults to the prefix before the first hyphen in the filename (`omarchy-theme-install` → `theme`), while the **name** defaults to the remaining suffix (`install`). The **summary** falls back to the first non-metadata comment line or a generated description like `Run the theme install command`. ## Required and Optional Metadata Keys The schema supports nine distinct metadata keys, each controlling specific router behaviors. ### Group and Name Routing The `group` and `name` keys define the command's position in the CLI hierarchy. If omitted, the router infers both from the binary filename using hyphen delimiters. ```bash # omarchy:group=theme # omarchy:name=install ``` This registers the command at the route `omarchy theme install`. ### Documentation Fields The `summary` key is **required** for proper help generation; without it, the router uses fallback parsing on comment lines. The `args` field specifies parameter placeholders, while `examples` provides pipe-separated invocations. ```bash # omarchy:summary=Install a new theme # omarchy:args=THEME_NAME # omarchy:examples=omarchy theme install nord|omarchy theme install dracula ``` ### Permission and Visibility Controls The `requires-sudo` key accepts only `true` or must be omitted entirely. Setting it to `true` forces privilege elevation before execution. The `hidden` key also accepts only `true` or omission; when `true`, the command excludes itself from default `omarchy commands` listings but remains callable directly. ```bash # omarchy:requires-sudo=true # omarchy:hidden=false ``` ### Alternative Routing with Aliases The `alias` and `aliases` keys (treated identically) create alternative routes that resolve to the same binary. Separate multiple aliases with pipes. ```bash # omarchy:aliases=omarchy theme add|omarchy theme new ``` ## Metadata Parsing in bin/omarchy The core implementation resides in `bin/omarchy`, the command-router script. During initialization, the `load_commands` function iterates through `bin/omarchy-*` executables, extracting metadata into the global associative arrays mentioned above. The parsed metadata serves three critical functions: 1. **Route Table Construction** – Populates `COMMAND_ROUTE` and `ROUTE_TO_KEY` mappings for dispatching subcommands 2. **Help Generation** – Enables `omarchy commands --help` to display formatted usage information derived from `COMMAND_USAGE` array values 3. **Validation Enforcement** – Powers `omarchy commands --check` to detect malformed metadata ## Practical Implementation Examples ### Defining a Complete Command Create `bin/omarchy-theme-install` with this header: ```bash #!/usr/bin/env bash # omarchy:group=theme # omarchy:name=install # omarchy:summary=Install a new theme # omarchy:args=THEME_NAME # omarchy:examples=omarchy theme install nord|omarchy theme install dracula # omarchy:requires-sudo=true # omarchy:aliases=omarchy theme add ``` When placed in the `bin/` directory, this automatically registers `omarchy theme install THEME_NAME` requiring sudo, with `omarchy theme add` as an alias. ### Validating Metadata Run the built-in checker to verify all command metadata: ```bash $ omarchy commands --check Command metadata check passed (123 commands) ``` The router validates that `requires-sudo` and `hidden` contain only `true` or are omitted. Invalid values trigger specific errors: ``` Invalid metadata in omarchy-theme-remove: hidden must be omitted or true ``` ### Querying Metadata Programmatically Source the router to inspect command metadata in scripts: ```bash #!/usr/bin/env bash source /usr/bin/omarchy load_commands printf 'Usage: %s\n' "${COMMAND_USAGE[omarchy-theme-install]}" ``` This outputs the constructed usage string: `omarchy theme install THEME_NAME`. ## Summary - **Omarchy commands** declare metadata via `# omarchy:` directives in the first 80 lines of Bash scripts stored in `bin/omarchy-*`. - **Nine metadata keys** control routing (`group`, `name`, `aliases`), documentation (`summary`, `args`, `examples`), and execution (`requires-sudo`, `hidden`). - **Router logic** in `bin/omarchy` (lines 202-236) parses directives into associative arrays using regex validation. - **Validation** via `omarchy commands --check` enforces strict typing for boolean fields and reports malformed metadata. - **Fallback behavior** infers `group` and `name` from filenames when omitted, ensuring backward compatibility. ## Frequently Asked Questions ### What happens if I omit the metadata comments entirely? The router falls back to filename-based inference. For a binary named `omarchy-network-configure`, it sets `group=network` and `name=configure`, then generates a default summary. However, `omarchy commands --check` may report warnings for missing documentation fields. ### Can I use false instead of omitting requires-sudo? No. The schema strictly validates that `requires-sudo` contains only the literal string `true` or is omitted entirely. Setting `# omarchy:requires-sudo=false` triggers a validation error in `omarchy commands --check` because the parser treats any non-true value as invalid. ### Where is the metadata schema documented in the repository? The primary documentation lives in [`docs/cli-router.md`](https://github.com/omacom/omarchy/blob/main/docs/cli-router.md) in the repository root. Additional context appears in [`AGENTS.md`](https://github.com/omacom/omarchy/blob/main/AGENTS.md), which references the `GROUP_DESCRIPTIONS` table used alongside command metadata for generating categorized help output. ### How do I hide a command from the default listing but keep it functional? Set `# omarchy:hidden=true` in the command's metadata header. This excludes the command from `omarchy commands` output and help listings, yet the route remains accessible via direct invocation and aliased paths.