Supported Metadata Keys in Omarchy Command Headers

Omarchy command headers support eight metadata keys—summary, args, requires-sudo, hidden, examples, group, name, and alias—that the bin/omarchy router extracts from the first 80 lines of executable scripts to generate help output, enforce permissions, and route aliases.

Omarchy, the opinionated Linux distribution maintained by Basecamp, embeds command metadata directly within executable comments rather than external configuration files. These declarative headers, documented in agents/skills/command-metadata.md, allow the CLI dispatcher to introspect capabilities, generate bash completions, and validate sudo requirements without executing the underlying code.

Supported Metadata Keys

The parser scans for lines matching the pattern # omarchy:key=value within the first 80 lines of any command file. According to the basecamp/omarchy source code, the router recognizes the following keys:

summary

Provides the human-readable description displayed in help listings and command indexes.

# omarchy:summary=Install, launch, stop, inspect, or remove the Windows VM

args

Documents the command-line arguments for usage displays and shell completion generation. This value is consumed by default/bash/completions to provide tab-completion hints.

# omarchy:args=<install|remove|launch|stop|status> [options]

requires-sudo

Accepts true or false to indicate whether the command must execute with elevated privileges. The dispatcher checks this flag before invoking the script.

# omarchy:requires-sudo=true

hidden

When set to true, excludes the command from auto-generated help menus while keeping it fully routable. Useful for internal utilities or beta features.

# omarchy:hidden=true

examples

One or more concrete usage samples separated by pipes (|). These appear in help output to demonstrate valid invocations.

# omarchy:examples=omarchy upgrade to quattro | omarchy upgrade to quattro --dev

group

Categorizes the command under a specific heading in the top-level help menu, organizing related utilities logically.

# omarchy:group=backup

name

Explicitly overrides the command name derived from the filename. This is essential for creating virtual commands or when the script filename differs from the desired invocation name.

# omarchy:name=test

alias

Declares alternate names that route to the same command implementation. Multiple aliases can be defined to provide backward compatibility or shorthand variants.

# omarchy:alias=omarchy parenthelp-alias

Implementation and Parsing Behavior

The metadata extraction logic resides in the CLI router (bin/omarchy) and is strictly enforced by the test suite in test/cli. The implementation behavior follows these rules:

• Line limit: Only the first 80 lines of a script are scanned for metadata headers.
• Case sensitivity: Keys must be lowercase and hyphenated exactly as documented in agents/skills/command-metadata.md.
• Value format: Values are treated as literal strings; boolean keys accept true or false string values.
• Routing priority: The name key takes precedence over the filename when determining how the command is invoked.

Removed and Ignored Keys

The parser deliberately ignores several deprecated keys that previously appeared in early drafts. The test suite explicitly verifies that these legacy fields are absent:

• legacy
• usage
• visibility
• mutates
• interactive

These keys are parsed but discarded, ensuring backward compatibility without affecting router behavior.

Practical Code Examples

Below are complete header sections demonstrating valid metadata configurations.

Standard visible command with full documentation:

#!/usr/bin/env bash

# omarchy:summary=Manage Windows virtual machines

# omarchy:args=<install|remove|launch|stop|status>

# omarchy:requires-sudo=true

# omarchy:group=vm

# omarchy:name=windows-vm

# omarchy:alias=vm

# omarchy:examples=omarchy windows-vm install | omarchy windows-vm status

Hidden administrative utility:

#!/usr/bin/env bash

# omarchy:summary=Internal cleanup routine

# omarchy:hidden=true

# omarchy:requires-sudo=false

Simple aliased command:

#!/usr/bin/env bash

# omarchy:summary=Display system backup status

# omarchy:group=backup

# omarchy:name=backup-status

# omarchy:alias=status

Summary

• Omarchy recognizes eight supported metadata keys: summary, args, requires-sudo, hidden, examples, group, name, and alias.

• Headers must appear within the first 80 lines of the script and follow the # omarchy:key=value syntax.

• The schema is formally defined in agents/skills/command-metadata.md and enforced by the test suite in test/cli.

• Deprecated keys including visibility, mutates, and interactive are explicitly ignored by the parser.

• The args key drives shell completion logic located in default/bash/completions.

Frequently Asked Questions

What is the exact syntax for Omarchy command metadata headers?

Metadata headers must begin with # omarchy: followed immediately by the key name, an equals sign, and the value. No spaces are permitted around the equals sign. The router scans the first 80 lines of the executable file for these patterns, as implemented in the bin/omarchy dispatcher.

Which metadata keys are deprecated or ignored by the Omarchy router?

The parser ignores the legacy keys usage, visibility, mutates, interactive, and legacy. The test suite in test/cli explicitly validates that these fields do not influence command behavior, ensuring they can remain in scripts for documentation purposes without affecting runtime logic.

How does the Omarchy CLI use the args metadata key?

The args value is extracted by the router to generate usage strings in help output and to provide completion hints via the scripts in default/bash/completions. It documents the expected positional arguments and options without enforcing them at the parser level.

Can a command have multiple aliases using the metadata system?

While the alias key accepts a single value, you can define multiple routing entries by creating separate wrapper scripts that share the same implementation or by using the alias key to point to a primary command name. The name key overrides the filename, allowing flexible routing configurations.

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