# Complete Guide to Omarchy Command Metadata Keys: group, name, summary, and More

> Explore Omarchy command metadata keys like group name and summary to enhance your CLI. Learn how to automatically discover and validate sub-commands with this comprehensive guide.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: deep-dive
- Published: 2026-09-11

---

**TLDR:** Omarchy command metadata keys are comment-based directives prefixed with `# omarchy:` that are embedded in executable scripts within the `bin/` directory, enabling the CLI to automatically discover, categorize, and validate sub-commands during the `register_command` routine.

The `omacom/omarchy` repository implements a self-documenting command architecture where **omarchy command metadata keys** embedded directly in shell scripts eliminate the need for external configuration. By parsing these directives during the `register_command` routine in `bin/omarchy`, the framework automatically constructs command routes, help text, and validation rules.

## How Omarchy Discovers Commands via Metadata

Omarchy discovers sub-commands by scanning executable scripts in the `bin/` directory. During the **`register_command`** routine implemented in **`bin/omarchy`**, the parser identifies lines matching the pattern:

```bash

# omarchy:<key>=<value>

```

This metadata extraction enables each `bin/omarchy-*` script to declaratively define its interface, routing, and documentation without modifying central configuration files.

## Core Identification Metadata Keys

### omarchy:group

The **group** key specifies the command category under which the command appears in `omarchy commands` listings. If omitted, Omarchy derives the group from the script filename using the pattern `omarchy-<group>-<name>`. For instance, a script named `omarchy-monitor-brightness` automatically defaults to group `monitor`.

### omarchy:name

The **name** key defines the human-readable command name that follows the group in the route hierarchy. When absent, the system defaults to the portion of the filename after the first hyphen.

### omarchy:summary

The **summary** key provides a one-sentence description displayed in command listings. If omitted, Omarchy falls back to the first non-metadata comment line in the script, or generates a generic "Run the <stem> command" placeholder if no comments exist.

## Usage and Documentation Metadata Keys

### omarchy:args

The **args** key defines argument placeholder syntax shown in usage lines, such as `[file]` or `<url>`. This free-form text helps users understand required inputs without examining the implementation.

### omarchy:examples

The **examples** key accepts a pipe-separated list of invocation patterns (e.g., `omarchy foo bar --verbose|omarchy foo bar --quiet`). The parser splits each pipe-delimited fragment and renders them as separate usage examples in help output.

## Routing and Access Control Metadata Keys

### omarchy:alias and omarchy:aliases

These keys define alternative routes that resolve to the same binary. Accepting pipe-separated full routes (e.g., `omarchy foo baz|omarchy f b`), they enable shorter or alternative command paths without duplicating scripts.

### omarchy:requires-sudo

When set to `true`, this boolean key marks the command as requiring elevated privileges. The value must be either omitted or the literal string `true`; any other value triggers a validation error during metadata checking.

### omarchy:hidden

Set to `true`, this key excludes the command from the default `omarchy commands` list. Like `requires-sudo`, it must be either omitted or exactly `true`; otherwise, `omarchy commands --check` reports an error.

## Metadata Validation and Fallback Behavior

When a script omits metadata keys, Omarchy applies sensible defaults:

- **group** → Parsed from the filename following the `omarchy-<group>-<name>` convention.
- **name** → Derived from the segment after the first hyphen in the filename.
- **summary** → Extracted from the first non-metadata comment line, or a generic placeholder.

During the **`omarchy commands --check`** validation routine, Omarchy enforces that:

- Each command supplies a `summary` (unless deliberately omitted).
- `requires-sudo` and `hidden` are either omitted or set exactly to `true`.

## Complete Implementation Example

The following script demonstrates all supported metadata keys in a single `bin/omarchy-foo-bar` executable:

```bash
#!/usr/bin/env bash

# omarchy:group=foo

# omarchy:name=bar

# omarchy:summary=Show bar status

# omarchy:args=[options]

# omarchy:examples=omarchy foo bar --verbose|omarchy foo bar --quiet

# omarchy:aliases=omarchy foo baz|omarchy f b

# omarchy:requires-sudo=true

# omarchy:hidden=true

# Additional implementation details here...

echo "Bar status: active"

```

Running `omarchy commands --check` validates this metadata against the schema without errors.

## Querying Metadata via JSON

You can inspect parsed metadata programmatically using the `--json` flag:

```bash
omarchy commands --json --all | jq '.commands[] | select(.binary=="omarchy-foo-bar")'

```

This outputs structured metadata including normalized fields:

```json
{
  "route": "omarchy foo bar",
  "binary": "omarchy-foo-bar",
  "group": "foo",
  "name": "bar",
  "summary": "Show bar status",
  "requires_sudo": true,
  "hidden": true,
  "args": "[options]",
  "examples": ["omarchy foo bar --verbose", "omarchy foo bar --quiet"],
  "aliases": ["omarchy foo baz", "omarchy f b"],
  "filename_route": "omarchy foo-bar",
  "routes": ["omarchy foo bar", "omarchy foo-bar", "omarchy foo baz", "omarchy f b"]
}

```

Note that metadata keys use hyphens (e.g., `requires-sudo`) while JSON fields use underscores (e.g., `requires_sudo`).

## Summary

- Omarchy command metadata keys use the `# omarchy:key=value` syntax in `bin/` scripts.

- The **`bin/omarchy`** script contains the `register_command` routine that parses these directives.
- **Core keys** include `group`, `name`, and `summary` for command categorization and display.
- **Routing keys** like `alias` and `aliases` enable multiple command paths to a single binary.
- **Boolean flags** `requires-sudo` and `hidden` must be set exactly to `true` or omitted entirely.
- **`omarchy commands --check`** validates metadata compliance and reports schema violations.
- Reference documentation lives in **[`agents/skills/command-metadata.md`](https://github.com/omacom/omarchy/blob/main/agents/skills/command-metadata.md)**.

## Frequently Asked Questions

### What happens if I omit the omarchy:group metadata key?

If you omit the `group` key, Omarchy derives it from the script filename using the pattern `omarchy-<group>-<name>`. For example, `omarchy-monitor-brightness` automatically assigns the group `monitor`.

### How does Omarchy validate the requires-sudo metadata key?

During `omarchy commands --check`, the validator ensures `requires-sudo` is either omitted or set to the literal string `true`. Any other value (including `True` or `yes`) triggers a validation error.

### Can I define multiple aliases for a single Omarchy command?

Yes, use the `omarchy:alias` or `omarchy:aliases` key with pipe-separated values. For example, `omarchy:aliases=omarchy foo baz|omarchy f b` creates two alternate routes that invoke the same binary.

### Where is the command metadata parsing logic implemented?

The parsing logic resides in the **`register_command`** function within **`bin/omarchy`**, which scans for `# omarchy:` comment patterns and processes them during CLI initialization.