Omarchy CLI Command Metadata Format: A Complete Guide to Command Headers

Omarchy CLI commands use structured comment headers starting with # omarchy:<key>=<value> in the first 80 lines of executable files to define routing, documentation, and execution behavior.

The basecamp/omarchy project implements a self-documenting command router that discovers binaries matching bin/omarchy-*. Rather than relying on external configuration files, each command binary declares its own metadata through specially formatted comment headers. This metadata format determines how commands appear in help listings, what arguments they accept, and whether they require elevated privileges.

Metadata Syntax and Parsing Rules

Comment Format Pattern

Omarchy metadata follows a strict key-value syntax embedded in shell comments:

# omarchy:<key>=<value>

Only lines beginning with # omarchy: are recognized as metadata directives. The router parses these declarations to build the command's routing table entry and help documentation.

Parsing Constraints

The metadata scanner imposes specific limits to ensure fast command discovery:

• Scan depth: Only the first 80 lines of the file are examined
• Termination: Parsing stops immediately at the first non-comment line
• Malformed entries: Unknown or malformed keys are silently ignored, causing the router to fall back to filename-derived defaults

Core Metadata Keys

The following keys control command presentation and execution in the Omarchy CLI:

Key	Value	Purpose
summary	string	Human-readable description; required for omarchy commands --check linting
args	string	Space-separated argument specification; brackets [ ] denote optional parameters
examples	string	One-line usage examples separated by pipe characters |
requires-sudo	true	Marks the command as requiring elevated privileges
hidden	true	Excludes the command from standard listings while keeping it routable
group	string	Overrides the group segment inferred from the filename
name	string	Overrides the command name inferred from the filename (supports spaces/hyphens)
alias	<route>	Registers an alternative route pointing to the same binary

Deprecated keys: The router explicitly ignores visibility, mutates, interactive, legacy, and usage. These removed keys must not appear in new commands.

How the Router Uses Metadata

The central router at bin/omarchy processes metadata headers during command discovery to build the routing table and validate command integrity.

Route Registration

Each binary registers two distinct routes according to the source code in docs/cli-router.md:

1. Canonical route: omarchy <group> <name> (after applying any group or name overrides)
2. Filename route: Derived by converting hyphens in the filename to spaces

If metadata overrides are absent, the router derives both values from the physical filename.

Collision Handling

When two binaries claim identical canonical routes, the first registration encountered wins. The router records conflicts for review via omarchy commands --check. Hidden commands still register their routes but omit themselves from standard listings.

Help and Lint Validation

The omarchy commands --check command enforces metadata compliance:

• Every command must provide an explicit # omarchy:summary= line

• Missing summaries or invalid boolean values trigger lint failures

• Aliases are flagged as such in command listings

Argument Validation

When a command declares non-empty args metadata, the router enforces argument presence. If a user invokes the command without arguments, bin/omarchy displays the command's help text rather than executing the binary.

Visibility Controls

Commands marked with # omarchy:hidden=true remain fully routable but disappear from omarchy commands output unless the user specifies the --all flag. This mechanism supports internal or plumbing commands that should not clutter primary listings.

Practical Implementation Examples

Standard Command with Arguments

The bin/omarchy-update binary demonstrates comprehensive metadata usage:

# omarchy:summary=Update Omarchy and system packages

# omarchy:args=[-y]

# omarchy:examples=omarchy update | omarchy update -y

# omarchy:requires-sudo=true

This header defines an optional -y flag, provides usage examples, and mandates sudo privileges.

Hidden Plumbing Commands

Compatibility wrappers use the hidden flag to avoid polluting command listings:

# omarchy:summary=Compatibility wrapper for omarchy-migrate-notify.

# omarchy:hidden=true

Route Aliases

The bin/omarchy-toggle-touchpad command creates an alternate access path:

# omarchy:summary=Toggle the touchpad on/off

# omarchy:alias=omarchy toggle touchpad

This allows users to invoke the command via either the canonical route or the human-readable alias.

Summary

• Omarchy CLI command metadata follows the pattern # omarchy:<key>=<value> within the first 80 lines of bin/omarchy-* files

• Required keys include summary (for lint compliance), while optional keys control routing (group, name, alias), privileges (requires-sudo), and visibility (hidden)

• The central router at bin/omarchy scans these headers to build canonical and filename-based routes, validate arguments, and generate help documentation

• Removed keys such as visibility, mutates, and interactive are explicitly ignored by the parser

• Metadata determines whether omarchy commands --check reports lint errors and whether bare invocations trigger help display instead of execution

Frequently Asked Questions

What happens if I omit the summary metadata?

The omarchy commands --check linting tool will flag your command as invalid. According to the router implementation in docs/cli-router.md, the summary field is mandatory for all commands, and missing values cause the lint check to fail even though the command remains callable.

Can metadata keys appear anywhere in the file?

No. Metadata comments must appear within the first 80 lines and before any executable code or non-comment lines. The parser stops scanning at the first non-comment line, so metadata appearing after shell commands will be ignored entirely.

How does the router handle command name conflicts?

When two binaries claim the same canonical route (group + name), the router registers the first one encountered and records the conflict for the --check command. The winning command remains functional while the duplicate route is flagged but unavailable to users.

Do hidden commands still work normally?

Yes. The hidden=true flag only affects list visibility. Hidden commands continue to register their routes and execute normally when invoked directly. They appear in omarchy commands output only when using the --all flag, making this ideal for internal plumbing or compatibility wrappers.

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