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

> Discover how Omarchy stores command metadata using structured comments in Bash scripts. Learn how the system parses key-value pairs for efficient command discovery.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: internals
- Published: 2026-09-08

---

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

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

```regex
^[[: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:

```bash
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:

```bash
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:

```bash
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.