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

> Learn how Omarchy CLI commands use metadata comments prefixed with # omarchy: for automatic help output generation. A complete guide for developers.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-20

---

**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.

```bash

# 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:

```bash
#!/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:

```bash
#!/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:

```bash

# 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:

```bash

# 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`](https://github.com/basecamp/omarchy/blob/quattro/bin/omarchy) |
| `bin/omarchy-toggle` | Example command with complete metadata | [`bin/omarchy-toggle`](https://github.com/basecamp/omarchy/blob/quattro/bin/omarchy-toggle) |
| [`agents/skills/command-metadata.md`](https://github.com/basecamp/omarchy/blob/main/agents/skills/command-metadata.md) | Developer guide for metadata conventions | [[`agents/skills/command-metadata.md`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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.