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

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:

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

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

#!/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.

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