How Omarchy Handles Command Aliases and Metadata Overrides

Omarchy treats every command as a Bash script whose header comments contain key-value metadata that the central dispatcher parses into associative arrays, enabling dynamic alias routing and allowing later metadata definitions to override earlier ones.

The basecamp/omarchy project implements a modular CLI architecture where commands are self-documenting Bash scripts. Each script's header comments define command aliases and metadata overrides that drive the system's routing, help generation, and validation. This design allows developers to modify command behavior and create shortcuts without altering the dispatcher's core logic.

Metadata Parsing in the Central Dispatcher

The Header Comment Pattern

In bin/omarchy, the dispatcher scans each command script for metadata blocks using a regex that matches comment lines starting with # followed by key=value pairs. The implementation extracts these pairs using the pattern ^#\s*([a-zA-Z_]+)=\s*(.*)$, treating every matched line as a configuration directive for the command.

Mapping Keys to Internal Variables

A case statement spanning lines 209-236 maps extracted keys to internal variables. Supported metadata fields include group, name, summary, args, examples, aliases, requires_sudo, and hidden. When the parser encounters the aliases key at line 228, it stores the pipe-separated values in a local variable for later processing.

Alias Collection and Routing Mechanisms

Storing Aliases in COMMAND_ALIASES

After parsing completes, the dispatcher stores the extracted aliases in the global associative array COMMAND_ALIASES around line 863. This array maps each individual alias to its canonical command key, enabling O(1) lookup during command execution. The storage occurs only after initial metadata validation, ensuring only syntactically correct aliases enter the routing table.

Runtime Resolution

The dispatcher iterates over the alias list at lines 303-308 to register each alias as a valid route pointing to the underlying command. When users invoke omarchy <alias>, the router resolves the alias to its canonical command key via the COMMAND_ALIASES lookup before executing the associated script.

Metadata Overrides and Validation

Overriding Values with Later Definitions

The metadata parser permits metadata overrides by design. Because the parser assigns the captured value to the same variable on every regex match, later occurrences of a key within the same header block overwrite earlier definitions. This behavior allows scripts to conditionally redefine summary text or modify aliases lists based on runtime environment detection.

Boolean Validation and Error Checking

The dispatcher validates metadata integrity at lines 231-236, flagging errors for non-boolean values assigned to requires_sudo or hidden. Additionally, the omarchy commands --check sub-command traverses the COMMAND_METADATA_ERRORS map around line 708 to report missing summaries or malformed alias definitions across the entire command suite.

Practical Implementation Examples

Define a command with aliases in your script header:

# ── Metadata block for bin/omarchy-theme-set ──

# name=Set Theme

# summary=Apply a theme to the current session

# aliases=theme|colors

# ── End metadata ──

# Script implementation follows...

This creates two valid invocations:

$ omarchy theme
$ omarchy colors

Both resolve to the same underlying command.

Inspect metadata for a specific command:

$ omarchy commands --metadata theme-set

Override aliases in a customized fork:

# aliases=theme|palette|scheme   # Adds palette and scheme; keeps theme

Validate all metadata and aliases:

$ omarchy commands --check

# → "Command metadata check passed (123 commands)"

# Or detailed errors if alias lines are malformed

Key Implementation Files

• bin/omarchy – The core dispatcher that parses metadata using the regex ^#\s*([a-zA-Z_]+)=\s*(.*)$, builds alias routing at lines 303-308, and validates overrides.
• test/shell.d/menu-test.sh – Test suite confirming that aliases are correctly normalized and matched in the menu system.
• docs/menu.md – Documentation of the menu schema, including the aliases field for menu items.
• docs/cli-router.md – Explanation of the CLI routing logic and how metadata drives command resolution.
• default/bash/aliases – Example of terminal aliases that invoke Omarchy agents, demonstrating external integration with the metadata system.

Summary

• The bin/omarchy dispatcher extracts metadata from Bash script headers using the regex pattern ^#\s*([a-zA-Z_]+)=\s*(.*)$ and a case statement at lines 209-236.
• Aliases are parsed from pipe-separated values in the aliases metadata field and stored in the COMMAND_ALIASES associative array around line 863.
• Runtime resolution occurs at lines 303-308, mapping alias invocations to their canonical commands before execution.
• Later metadata definitions automatically override earlier ones within the same script, enabling dynamic configuration.
• The omarchy commands --check sub-command validates metadata integrity, catching malformed booleans and missing required fields by inspecting COMMAND_METADATA_ERRORS.

Frequently Asked Questions

How does the omarchy dispatcher parse metadata from command scripts?

The dispatcher reads each command script line-by-line, applying the regex ^#\s*([a-zA-Z_]+)=\s*(.*)$ to identify key-value pairs in header comments. A case statement at lines 209-236 routes these keys to specific variables such as aliases, summary, and requires_sudo, populating the command's metadata profile before execution.

How are aliases stored internally in Omarchy?

After parsing the aliases key from a script's metadata header, the dispatcher stores the pipe-separated list in the global COMMAND_ALIASES associative array around line 863. This array maps each individual alias to its canonical command key, enabling efficient lookup during the routing phase at lines 303-308.

Can metadata values be overridden within the same script?

Yes. The parser assigns values to metadata variables on every regex match, so later definitions naturally overwrite earlier ones. This behavior allows scripts to redefine summary text or modify aliases lists dynamically, though the final values must pass boolean validation at lines 231-236 to ensure fields like requires_sudo contain only true/false values.

How do I validate that my command aliases are correctly configured?

Run omarchy commands --check to trigger the validation engine, which inspects the COMMAND_METADATA_ERRORS map around line 708 for malformed entries. The checker verifies that aliases contain valid pipe-separated strings and that boolean fields contain only true/false values, reporting specific line numbers for any violations.

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