How Omarchy CLI Commands Are Documented with Metadata Comments: A Complete Guide

Omarchy CLI commands use self-documenting metadata comments prefixed with # omarchy: that are parsed by the central dispatcher script to automatically generate help output.

The Omarchy framework embeds command documentation directly in source files through a structured comment convention. This keeps documentation synchronized with implementation and eliminates the need for separate manual pages. The bin/omarchy driver script scans executable files in bin/, extracts these metadata comments, and constructs the help system that powers both omarchy --help and command-specific help.

Understanding the # omarchy: Metadata Convention

Omarchy commands are standalone executable scripts in the bin/ directory. Each script declares its documentation through specially formatted comments at the top of the file. The dispatcher recognizes five core metadata tags that control how commands appear in help listings.

Required and Optional Metadata Tags

Tag	Purpose	Required
# omarchy:description=	Human-readable command summary	Yes

| # omarchy:examples= | Usage examples shown in help | No |

| # omarchy:group= | Command category prefix (e.g., toggle-, theme-) | No |

| # omarchy:hidden= | Excludes command from public listings when true | No |

| # omarchy:flags= | Declares supported command-line flags | No |

The Central Dispatcher: How bin/omarchy Parses Metadata

The file bin/omarchy serves as the single entry point for all CLI operations. When invoked, it:

1. Iterates through executables in bin/

2. Extracts lines matching ^# omarchy:

3. Populates a COMMAND_METADATA data structure

4. Generates formatted help output from this structure

This architecture ensures that adding or modifying a command automatically updates the help system—no manual registry edits required.

# From bin/omarchy (simplified conceptual flow)

# The actual implementation scans bin/ for metadata comments

for cmd in bin/omarchy-*; do
  description=$(grep "^# omarchy:description=" "$cmd" | cut -d= -f2-)

  examples=$(grep "^# omarchy:examples=" "$cmd" | cut -d= -f2-)

  group=$(grep "^# omarchy:group=" "$cmd" | cut -d= -f2-)

  # ...build COMMAND_METADATA...

done

Real-World Metadata Examples

Standard Command with Full Metadata

The bin/omarchy-toggle script demonstrates complete metadata coverage:

#!/bin/bash

# omarchy:description=Enable or disable a feature flag

# omarchy:examples=omarchy toggle nightlight | omarchy toggle nightlight on

# omarchy:group=toggle

# omarchy:flags=--status,--force

omarchy-toggle() {
  local flag="$1"
  local action="${2:-toggle}"
  
  case "$action" in
    on)  enable_feature "$flag" ;;
    off) disable_feature "$flag" ;;
    *)   toggle_feature "$flag" ;;
  esac
}

Running omarchy toggle --help extracts and formats this metadata:

Usage: omarchy toggle <flag> [on|off]

Enable or disable a feature flag

Examples:
  omarchy toggle nightlight
  omarchy toggle nightlight on

Flags:
  --status    Show current state without changing
  --force     Apply even if safety checks fail

Hidden Internal Commands

For utilities that should not appear in public listings, the hidden tag prevents discovery while preserving functionality:

#!/bin/bash

# omarchy:hidden=true

# omarchy:description=Internal utility for updating the version file

omarchy-version-update() {
  local new_version="$1"
  echo "$new_version" > "$OMARCHY_ROOT/VERSION"
  # Additional update logic...

}

This command remains invokable internally but never appears in omarchy --help output.

Group-Based Command Organization

The group tag creates logical command families. Commands sharing a group prefix are clustered in help listings:

# omarchy:group=toggle

# Results in: omarchy toggle-* commands grouped under "Toggle Commands"

Common group values in the Omarchy codebase include:

• toggle — Feature enablement commands
• theme — Appearance and styling commands
• config — Configuration management utilities

Flag Declaration and Validation

The flags tag enables the dispatcher to validate arguments before execution:

# omarchy:flags=--verbose,--dry-run,--config=PATH

This declaration:

• Documents available options in help output
• Allows the driver to reject unrecognized flags early
• Supports value-bearing flags with = notation

Key Files in the Metadata System

File	Function	Link
bin/omarchy	Central dispatcher; parses metadata and generates help	bin/omarchy
bin/omarchy-toggle	Example command with complete metadata	bin/omarchy-toggle
agents/skills/command-metadata.md	Developer guide for metadata conventions	[agents/skills/command-metadata.md](https://github.com/basecamp/omarchy/blob/quattro/agents/skills/command-metadata.md)

Summary

• Omarchy uses # omarchy: prefixed comments embedded directly in command source files for self-documenting CLI tools

• The bin/omarchy dispatcher automatically discovers and parses these comments to build dynamic help output

• Five metadata tags control visibility, grouping, examples, and flag validation

• Documentation stays synchronized with code because it lives in the same file as implementation

• Hidden commands support internal tooling without polluting public interfaces

Frequently Asked Questions

What happens if a command is missing required metadata?

The bin/omarchy dispatcher typically skips commands without a description tag or assigns default placeholder text. Commands remain functional but appear with minimal help information. The agents/skills/command-metadata.md guide recommends always including at minimum a description for discoverability.

Can metadata comments be placed anywhere in the file?

Metadata comments must appear at the top of the file before any executable code. The dispatcher reads files sequentially and stops parsing metadata after encountering the first non-comment line. This ensures predictable extraction performance.

How does the metadata system handle multi-line descriptions?

The current implementation treats each # omarchy:description= line as a single value. For longer descriptions, the convention uses multiple related tags or concise single-line summaries. The examples tag accepts pipe-separated values (|) to provide multiple usage patterns compactly.

Is there a schema or linter for metadata comments?

The Omarchy repository includes conventions documented in agents/skills/command-metadata.md. While no automated linter exists in the core distribution, the dispatcher validates flag syntax at runtime and reports malformed entries during help generation.

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