How Omarchy Stores and Reads Command Metadata: Inside the Bash-Based Discovery System

Omarchy stores command metadata as structured comment blocks within individual Bash scripts in the bin/ directory, then parses these key-value pairs into associative arrays using regex pattern matching in the central bin/omarchy driver.

Omarchy is an open-source Bash-based command framework that treats each executable in its bin/ directory as a self-documenting command. Understanding how Omarchy command metadata is stored and accessed reveals a lightweight yet robust discovery mechanism that eliminates separate configuration files by embedding documentation directly in executable scripts.

Metadata Storage in Command Scripts

The Comment-Based Metadata Block

Each command implementation in the Omarchy repository stores its metadata as structured comment lines at the top of the file. This design keeps documentation colocated with the logic it describes, using a simple key=value syntax prefixed by hash symbols.

The recognized metadata fields include:

• group – Categorizes the command (e.g., toggle, config)
• name – Human-readable identifier
• summary – Brief description shown in help output
• args – Argument specification string
• examples – Usage examples
• aliases – Alternative command names
• requires_sudo – Boolean flag (true if sudo required)
• hidden – Boolean flag (true to hide from UI)

#!/usr/bin/env bash

# group=toggle

# name=omarchy-toggle-nightlight

# summary=Toggle Night Light on/off

# hidden=true

# ... implementation logic ...

The Parsing Engine in bin/omarchy

File Discovery and Processing

The core driver script bin/omarchy discovers available commands by iterating through every file in the bin/ directory. For each command file, the driver reads the content line-by-line to extract metadata before storing it in memory.

Regex Pattern Matching

The parsing logic uses Bash regex matching to identify metadata lines. According to the source code in bin/omarchy, the pattern employed is:

^[[:space:]]*#?[[:space:]]*([A-Za-z_]+)=(.*)$

This regular expression allows for optional whitespace and optional hash symbols, providing flexibility in formatting. When a line matches, Bash populates the BASH_REMATCH array with the captured key and value:

while IFS= read -r line; do
    if [[ $line =~ ^[[:space:]]*#?[[:space:]]*([A-Za-z_]+)=(.*)$ ]]; then
        metadata_key=${BASH_REMATCH[1]}
        metadata_value=${BASH_REMATCH[2]}
        # ... storage logic ...

    fi
done < "$cmd_file"

Populating Associative Arrays

The extracted metadata is stored in a schema of associative arrays indexed by command key. As implemented in bin/omarchy, the driver maintains the following data structures:

Array	Purpose
COMMAND_GROUP[$key]	Functional category
COMMAND_NAME[$key]	Display name
COMMAND_SUMMARY[$key]	Help text description
COMMAND_ARGS[$key]	Parameter specification
COMMAND_EXAMPLES[$key]	Usage examples
COMMAND_ALIASES[$key]	Command aliases
COMMAND_REQUIRES_SUDO[$key]	Sudo requirement flag
COMMAND_HIDDEN[$key]	Visibility flag
COMMAND_BINARY[$key]	Path to executable

The storage logic uses a case statement to route keys to their respective arrays according to the Omarchy command metadata specification:

case "$metadata_key" in
    group)       COMMAND_GROUP[$key]="$metadata_value" ;;
    name)        COMMAND_NAME[$key]="$metadata_value" ;;
    summary)     COMMAND_SUMMARY[$key]="$metadata_value" ;;
    args)        COMMAND_ARGS[$key]="$metadata_value" ;;
    examples)    COMMAND_EXAMPLES[$key]="$metadata_value" ;;
    aliases)     COMMAND_ALIASES[$key]="$metadata_value" ;;
    requires_sudo)
        COMMAND_REQUIRES_SUDO[$key]="$metadata_value"
        [[ $metadata_value == "true" ]] ||
            metadata_errors=$(append_pipe_value "$metadata_errors" "requires-sudo must be omitted or true")
        ;;
    hidden)
        COMMAND_HIDDEN[$key]="$metadata_value"
        [[ $metadata_value == "true" ]] ||
            metadata_errors=$(append_pipe_value "$metadata_errors" "hidden must be omitted or true")
        ;;
esac

Metadata Validation and Error Handling

Field Validation (Lines 210-239)

The bin/omarchy script validates metadata constraints during the parsing phase. Boolean fields like requires_sudo and hidden must either be omitted or explicitly set to true. Any other value triggers an error accumulation mechanism using the append_pipe_value helper function. This validation logic resides around lines 210-239 of the driver script.

Runtime Error Reporting (Lines 710-733)

After parsing completes, the driver performs final validation checks. If a command lacks a summary field, the system reports:

if [[ -z $summary ]]; then
    echo "Missing metadata summary: ${COMMAND_BINARY[$key]}" >&2
fi

Additionally, any accumulated validation errors from the parsing phase are reported to standard error. This error reporting mechanism appears around lines 710-733 in bin/omarchy, ensuring that malformed metadata is caught before the command is presented to users.

Group Descriptions and UI Organization

The GROUP_DESCRIPTIONS Array (Lines 27-97)

While individual commands store their own metadata, the human-readable descriptions for command categories are maintained centrally. In bin/omarchy, the associative array GROUP_DESCRIPTIONS maps group identifiers to their descriptions. This array is populated at lines 27-97 of the driver script, allowing the help system to display contextual information about each command category (such as toggle, config, or system) separately from the individual command summaries.

Summary

• Omarchy command metadata is embedded as comment lines (# key=value) at the top of each executable in bin/

• The central driver bin/omarchy parses these comments using the regex pattern ^[[:space:]]*#?[[:space:]]*([A-Za-z_]+)=(.*)$

• Parsed values populate associative arrays including COMMAND_GROUP, COMMAND_NAME, COMMAND_SUMMARY, and COMMAND_REQUIRES_SUDO

• Validation occurs during parsing (lines 210-239) and final checking (lines 710-733), ensuring boolean fields are strictly true or absent, and required fields like summary are present

• Group-level descriptions are stored in the GROUP_DESCRIPTIONS array defined at lines 27-97 of bin/omarchy

Frequently Asked Questions

What file format must command metadata follow in Omarchy?

Metadata must appear as comment lines at the beginning of each command script in the bin/ directory, using the format # key=value. Valid keys include group, name, summary, args, examples, aliases, requires_sudo, and hidden. The regex parser allows optional whitespace and optional hash symbols, but the key must match [A-Za-z_]+.

How does Omarchy validate command metadata during discovery?

The bin/omarchy driver validates metadata in two phases. During parsing (around lines 210-239), it verifies that boolean fields like requires_sudo and hidden are either omitted or set exactly to true. During final assembly (around lines 710-733), it checks that every command has a non-empty summary field, reporting errors to standard error if validation fails.

Where are command group descriptions defined in Omarchy?

Group descriptions are not stored in individual command files. Instead, they are defined centrally in the GROUP_DESCRIPTIONS associative array within bin/omarchy, specifically at lines 27-97. This array maps group identifiers (like toggle or system) to human-readable strings displayed in the help interface.

Can Omarchy command metadata contain multiline values?

Based on the parsing implementation in bin/omarchy, each metadata key-value pair must reside on a single line matching the pattern ^[[:space:]]*#?[[:space:]]*([A-Za-z_]+)=(.*)$. The regex captures everything after the equals sign into a single value, so while newlines within a value are not supported by the parser, long strings can be stored as single-line values.

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