# How Command Metadata Is Loaded in Omarchy: The bin/omarchy Discovery Mechanism

> Discover how Omarchy loads command metadata by scanning bin/omarchy scripts and parsing comment annotations for instant runtime lookup. Learn the discovery mechanism.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: internals
- Published: 2026-08-27

---

**TLDR:** Omarchy loads command metadata by scanning executable scripts matching the `bin/omarchy-*` pattern, sourcing each file to parse specially-formatted comment annotations (such as `# omarchy:desc`), and registering the extracted values into Bash associative arrays named `CMD_DESC`, `CMD_GROUP`, and `CMD_HIDDEN` for instant runtime lookup.

The **Omarchy** CLI framework avoids static command registries by implementing a dynamic discovery system directly in the `bin/omarchy` dispatcher script. This approach allows developers to add new commands simply by creating a new executable file, without modifying any central command list. The system automatically extracts descriptive metadata from each script to power help menus, groupings, and visibility controls.

## The Discovery Phase: Enumerating Command Scripts

The loading process begins in the main `bin/omarchy` dispatcher, which locates all available command implementations using a glob pattern. The dispatcher iterates over every executable file matching `bin/omarchy-*` and sources them in a subshell to capture their metadata definitions.

This discovery mechanism relies on a standard `for` loop that processes files alphabetically:

```bash

# Inside bin/omarchy - Discovery loop

for cmd in "$ROOT/bin/omarchy-"*; do
  # Extract command name by stripping path and prefix

  name="${cmd##*/omarchy-}"
  
  # Source the script to load OMARCHY_* variables into current scope

  source "$cmd"
done

```

By sourcing each script, the dispatcher executes any variable assignments present in the file header, making **command metadata** immediately available as shell variables before the actual command functions are invoked.

## Parsing Comment Annotations

Each command script defines its metadata through specially-formatted comment lines that follow the pattern `# omarchy:<key>=<value>`. The dispatcher parses these annotations to populate standardized variables that describe the command's behavior and presentation.

The recognized metadata fields include:

- **`# omarchy:desc="..."`** – Sets the human-readable description displayed in help listings

- **`# omarchy:group="..."`** – Assigns the command to a logical category for menu organization  

- **`# omarchy:hidden=true`** – Flags the command as hidden, excluding it from standard UI menus while keeping it callable

When a script is sourced, these comments effectively translate into variable assignments like `OMARCHY_DESC`, `OMARCHY_GROUP`, and `OMARCHY_HIDDEN`. The dispatcher uses `eval` or direct variable expansion to capture these values into the metadata registration system.

## Registration in Associative Arrays

After extracting metadata from a command script, `bin/omarchy` stores the data in three Bash associative arrays that serve as the runtime registry. These arrays use the bare command name (e.g., `theme-set`) as the key.

The storage mechanism uses `declare -A` to initialize the structures:

```bash

# Registration in bin/omarchy

declare -A CMD_DESC   # Stores human-readable descriptions

declare -A CMD_GROUP  # Stores grouping information  

declare -A CMD_HIDDEN # Stores visibility flags (true/false)

# Populating the arrays after sourcing each command script

CMD_DESC[$name]="${OMARCHY_DESC:-$name}"
CMD_GROUP[$name]="${OMARCHY_GROUP:-misc}"
CMD_HIDDEN[$name]="${OMARCHY_HIDDEN:-false}"

```

This associative array approach enables O(1) lookup performance when the CLI needs to retrieve metadata for generating help text or filtering visible commands. The arrays persist in memory for the duration of the shell session, eliminating the need to re-parse script files on every metadata query.

## Example: Defining Metadata in a Command Script

To illustrate the complete flow, consider a hypothetical `bin/omarchy-weather-status` script. The metadata loads automatically when the dispatcher sources this file during initialization.

```bash
#!/usr/bin/env bash

# omarchy:desc="Display current weather conditions"

# omarchy:group="utilities"

# omarchy:hidden=false

weather_status() {
  # Command implementation logic here

  echo "Current: Sunny, 72°F"
}

```

When `bin/omarchy` sources this script, it captures:
- `OMARCHY_DESC` = "Display current weather conditions"
- `OMARCHY_GROUP` = "utilities"  
- `OMARCHY_HIDDEN` = "false"

These values immediately populate `CMD_DESC[weather-status]`, `CMD_GROUP[weather-status]`, and `CMD_HIDDEN[weather-status]` in the dispatcher's metadata registry.

## Summary

- The `bin/omarchy` dispatcher dynamically discovers commands by globbing `bin/omarchy-*` scripts and sourcing each file to extract metadata.
- Metadata is declared via comment annotations using the `# omarchy:<field>=<value>` syntax, which sets variables like `OMARCHY_DESC` and `OMARCHY_GROUP`.

- Parsed metadata registers into three associative arrays—`CMD_DESC`, `CMD_GROUP`, and `CMD_HIDDEN`—enabling fast lookups for help generation and UI filtering.
- Hidden commands (marked with `# omarchy:hidden=true`) remain callable directly but are excluded from automatic menu listings.

- Adding new commands requires no registry edits; simply creating a `bin/omarchy-<name>` script with proper metadata comments automatically includes it in the CLI.

## Frequently Asked Questions

### What happens if a command script omits the metadata comments?

If a script lacks metadata annotations, the registration phase applies sensible defaults. The `CMD_DESC` array falls back to the command name itself, `CMD_GROUP` defaults to `"misc"`, and `CMD_HIDDEN` defaults to `"false"`, ensuring the command remains visible and functional even without explicit metadata.

### Can hidden commands still be executed by users?

Yes. Setting `# omarchy:hidden=true` only removes the command from automatically generated help menus and UI listings. The command remains fully executable when invoked directly by name (e.g., `omarchy internal-utility`), making hidden flags ideal for administrative or debugging tools that should not clutter the standard interface.

### Where does the metadata parsing logic reside in the source tree?

The core discovery and registration logic lives entirely in **`bin/omarchy`**, the main entry point script. Individual command implementations reside in separate files matching the **`bin/omarchy-*`** pattern, each containing their own metadata headers. No external configuration files or separate metadata manifests are required for the system to function.