Understanding Metadata Comments in Omarchy Commands: A Complete Guide

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 and documented in 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:

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

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

#!/usr/bin/env bash

# omarchy:hidden=true

# omarchy:summary=Internal apply-hardware plumbing

Reading metadata programmatically (as implemented in the router):

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

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