Omarchy CLI Commands Metadata Keys: Complete Reference Guide

Omarchy CLI commands support eight distinct metadata keys—group, name, summary, args, examples, alias/aliases, hidden, and requires-sudo—that are extracted from comment lines near the top of executable scripts to control routing, documentation, and visibility.

The Omarchy framework by Basecamp uses a declarative metadata system to define CLI behavior directly within bash scripts located in the bin/ directory. Understanding the supported metadata keys for Omarchy CLI commands is essential for extending the toolchain, as these declarations determine how commands are categorized, named, and presented to users without modifying the central router logic.

How Omarchy Parses Command Metadata

When the Omarchy router (bin/omarchy) initializes, it scans the first 80 lines of every executable script in bin/ to extract metadata declarations. The router looks for comments matching the strict pattern # omarchy:<key>=<value> and processes them within the register_command function. According to the basecamp/omarchy source code, a case block in bin/omarchy (lines 11–19) handles the parsing logic for each supported key, mapping valid metadata to internal command structures.

Supported Metadata Keys

The authoritative list of supported metadata keys is documented in agents/skills/command-metadata.md. Each key overrides default behaviors inferred from filenames or provides additional context for help generation.

group – Override Command Grouping

The # omarchy:group=… key overrides the command group that would otherwise be inferred from the filename. This allows scripts to organize logically under different namespaces regardless of their physical location.

name – Override Command Name

Use # omarchy:name=… to specify the sub-command name that appears after the group. This overrides the default name extraction from the filename, enabling cleaner or more descriptive command interfaces.

summary – Define Help Text

The # omarchy:summary=… key provides a short description that appears in command listings. This text is displayed when users run omarchy --help or list commands within a group.

args – Document Usage Arguments

Use # omarchy:args=… to describe positional or optional arguments using concise notation (e.g., [smart|region] or <theme-name>). This key populates the usage section of help output.

examples – Provide Usage Examples

The # omarchy:examples=… key accepts one or more example invocations separated by the pipe character |. Only use this when arguments require illustration, as it renders concrete usage patterns in help text.

alias and aliases – Create Alternate Routes

Both # omarchy:alias=… and # omarchy:aliases=… (plural form) provide alternate routes that map to the same command implementation. This allows multiple command names to trigger identical functionality without duplicating scripts.

hidden – Suppress from Listings

Setting # omarchy:hidden=true marks the command as hidden. Hidden commands are omitted from default command listings unless the user explicitly requests --all, making this ideal for deprecated or advanced utilities.

requires-sudo – Flag Privilege Requirements

The # omarchy:requires-sudo=true key flags commands that require elevated privileges. The value must be either omitted or explicitly set to true; when present, Omarchy can warn users or automatically escalate privileges before execution.

Implementation in the Router

The metadata extraction logic resides in bin/omarchy, specifically within the register_command function. As implemented in basecamp/omarchy, the router uses a case statement to process each metadata key, validating and assigning values to command properties. The agents/skills/command-metadata.md file serves as the contract reference, ensuring consistency between the parser implementation and developer documentation.

Practical Code Examples

The following examples demonstrate complete metadata declarations in executable bash scripts:

#!/usr/bin/env bash

# omarchy:summary=Take a screenshot

# omarchy:args=[smart|region|fullscreen] [slurp|copy]

# omarchy:examples=omarchy screenshot | omarchy capture screenshot region

# omarchy:alias=screenshot

# omarchy:requires-sudo=true

# omarchy:hidden=true

# … implementation of the screenshot command …

#!/usr/bin/env bash

# omarchy:group=theme

# omarchy:name=set

# omarchy:summary=Apply a theme

# omarchy:args=<theme-name>

# omarchy:examples=omarchy theme set SolarizedDark | omarchy theme set Nord

# … implementation of the theme‑set command …

Summary

• Omarchy extracts metadata from the first 80 lines of scripts in bin/ using the pattern # omarchy:<key>=<value>.

• Eight keys control command behavior: group, name, summary, args, examples, alias/aliases, hidden, and requires-sudo.

• The register_command function in bin/omarchy processes these declarations using a case block (lines 11–19).

• Reference documentation lives in agents/skills/command-metadata.md, defining the contract for all Omarchy CLI metadata.

• Metadata allows scripts to override filename-derived defaults, provide usage examples, create aliases, and flag sudo requirements.

Frequently Asked Questions

What is the exact syntax for declaring metadata in Omarchy commands?

Metadata declarations must follow the strict format # omarchy:<key>=<value> as comments near the top of executable scripts. The router only scans the first 80 lines of each file, and keys must match those handled in the register_command function's case block within bin/omarchy.

Can a single Omarchy command have multiple aliases?

Yes. Use either # omarchy:alias=… for a single alternate route or # omarchy:aliases=… when declaring multiple aliases. Both keys are processed by the same logic in the router, allowing multiple command paths to map to a single implementation.

Where is the authoritative list of supported metadata keys documented?

The definitive reference lives in agents/skills/command-metadata.md within the basecamp/omarchy repository. This file serves as the contract between the router implementation (bin/omarchy) and command developers, detailing valid keys and their expected values.

How does Omarchy handle commands that require elevated privileges?

Commands requiring root access should declare # omarchy:requires-sudo=true. This metadata flag alerts the system that the command needs sudo privileges, allowing Omarchy to handle privilege escalation or display appropriate warnings before execution.

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