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

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:

# 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 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:

#!/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:

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

This outputs structured metadata including normalized fields:

{
  "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.

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}