Understanding the Metadata Format for Omarchy Commands: A Complete Guide

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), ensuring the metadata overhead remains minimal during startup.

The canonical reference for supported keys lives in agents/skills/command-metadata.md, while the parsing logic and route-building algorithm are documented in 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=<value> – Assigns the command to a logical category (e.g., # omarchy:group=backup).

• # omarchy:name=<value> – Sets the command identifier (e.g., # omarchy:name=restore).

Documentation Fields

These keys populate the help system and command listings:

• # omarchy:summary=<text> – 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=<pattern> – 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=<list> – 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=<name> or # omarchy:aliases=<name> – 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.

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

Phase 2: Metadata Assembly When the fast path fails, the router:

1. Splits the filename omarchy-<group>-<name> at hyphens to generate default routes.
2. Parses the comment header for omarchy: directives.
3. Constructs the canonical route (omarchy <group> <name>) 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

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

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

#!/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 and 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=<name> or the plural form # omarchy:aliases=<name>. 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.

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