Metadata Schema for Omarchy Commands: Complete CLI Routing Guide

The Omarchy CLI uses a declarative metadata schema where Bash commands define routing, permissions, and documentation through specially formatted comment directives prefixed with # omarchy:.

This metadata schema powers the command-router in the omacom/omarchy repository, enabling automatic route generation, help text creation, and permission enforcement for the Omarchy dotfiles manager. Understanding this schema is essential for extending the CLI or troubleshooting routing issues.

How the Metadata Schema Works

Omarchy commands are executables stored in bin/omarchy-* files. When the router loads a command binary, it scans the first 80 lines (defined by METADATA_SCAN_LIMIT) for directives starting with # omarchy:.

The router parses these directives using a regular expression at lines 202-236 of bin/omarchy:

^[[:space:]]*#[[:space:]]*omarchy:([[:alnum:]_-]+)=(.*)$

Matched directives populate associative arrays that drive the CLI behavior:

• COMMAND_GROUP – categorizes commands (e.g., theme, update)
• COMMAND_NAME – the action name in the route
• COMMAND_SUMMARY – description for help output
• COMMAND_ARGS – argument placeholders
• COMMAND_EXAMPLES – usage examples
• COMMAND_REQUIRES_SUDO – privilege requirements
• COMMAND_HIDDEN – visibility in listings
• COMMAND_ALIASES – alternative routes

If metadata is missing, the router applies fallback logic: the group defaults to the prefix before the first hyphen in the filename (omarchy-theme-install → theme), while the name defaults to the remaining suffix (install). The summary falls back to the first non-metadata comment line or a generated description like Run the theme install command.

Required and Optional Metadata Keys

The schema supports nine distinct metadata keys, each controlling specific router behaviors.

Group and Name Routing

The group and name keys define the command's position in the CLI hierarchy. If omitted, the router infers both from the binary filename using hyphen delimiters.

# omarchy:group=theme

# omarchy:name=install

This registers the command at the route omarchy theme install.

Documentation Fields

The summary key is required for proper help generation; without it, the router uses fallback parsing on comment lines. The args field specifies parameter placeholders, while examples provides pipe-separated invocations.

# omarchy:summary=Install a new theme

# omarchy:args=THEME_NAME

# omarchy:examples=omarchy theme install nord|omarchy theme install dracula

Permission and Visibility Controls

The requires-sudo key accepts only true or must be omitted entirely. Setting it to true forces privilege elevation before execution. The hidden key also accepts only true or omission; when true, the command excludes itself from default omarchy commands listings but remains callable directly.

# omarchy:requires-sudo=true

# omarchy:hidden=false

Alternative Routing with Aliases

The alias and aliases keys (treated identically) create alternative routes that resolve to the same binary. Separate multiple aliases with pipes.

# omarchy:aliases=omarchy theme add|omarchy theme new

Metadata Parsing in bin/omarchy

The core implementation resides in bin/omarchy, the command-router script. During initialization, the load_commands function iterates through bin/omarchy-* executables, extracting metadata into the global associative arrays mentioned above.

The parsed metadata serves three critical functions:

1. Route Table Construction – Populates COMMAND_ROUTE and ROUTE_TO_KEY mappings for dispatching subcommands
2. Help Generation – Enables omarchy commands --help to display formatted usage information derived from COMMAND_USAGE array values
3. Validation Enforcement – Powers omarchy commands --check to detect malformed metadata

Practical Implementation Examples

Defining a Complete Command

Create bin/omarchy-theme-install with this header:

#!/usr/bin/env bash

# omarchy:group=theme

# omarchy:name=install

# omarchy:summary=Install a new theme

# omarchy:args=THEME_NAME

# omarchy:examples=omarchy theme install nord|omarchy theme install dracula

# omarchy:requires-sudo=true

# omarchy:aliases=omarchy theme add

When placed in the bin/ directory, this automatically registers omarchy theme install THEME_NAME requiring sudo, with omarchy theme add as an alias.

Validating Metadata

Run the built-in checker to verify all command metadata:

$ omarchy commands --check
Command metadata check passed (123 commands)

The router validates that requires-sudo and hidden contain only true or are omitted. Invalid values trigger specific errors:

Invalid metadata in omarchy-theme-remove: hidden must be omitted or true

Querying Metadata Programmatically

Source the router to inspect command metadata in scripts:

#!/usr/bin/env bash
source /usr/bin/omarchy
load_commands
printf 'Usage: %s\n' "${COMMAND_USAGE[omarchy-theme-install]}"

This outputs the constructed usage string: omarchy theme install THEME_NAME.

Summary

• Omarchy commands declare metadata via # omarchy: directives in the first 80 lines of Bash scripts stored in bin/omarchy-*.

• Nine metadata keys control routing (group, name, aliases), documentation (summary, args, examples), and execution (requires-sudo, hidden).

• Router logic in bin/omarchy (lines 202-236) parses directives into associative arrays using regex validation.

• Validation via omarchy commands --check enforces strict typing for boolean fields and reports malformed metadata.

• Fallback behavior infers group and name from filenames when omitted, ensuring backward compatibility.

Frequently Asked Questions

What happens if I omit the metadata comments entirely?

The router falls back to filename-based inference. For a binary named omarchy-network-configure, it sets group=network and name=configure, then generates a default summary. However, omarchy commands --check may report warnings for missing documentation fields.

Can I use false instead of omitting requires-sudo?

No. The schema strictly validates that requires-sudo contains only the literal string true or is omitted entirely. Setting # omarchy:requires-sudo=false triggers a validation error in omarchy commands --check because the parser treats any non-true value as invalid.

Where is the metadata schema documented in the repository?

The primary documentation lives in docs/cli-router.md in the repository root. Additional context appears in AGENTS.md, which references the GROUP_DESCRIPTIONS table used alongside command metadata for generating categorized help output.

How do I hide a command from the default listing but keep it functional?

Set # omarchy:hidden=true in the command's metadata header. This excludes the command from omarchy commands output and help listings, yet the route remains accessible via direct invocation and aliased paths.

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