# How Omarchy Handles Command Aliases and Metadata Overrides

> Discover how Omarchy parses Bash script header comments into key-value metadata for dynamic alias routing and handles metadata overrides.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-26

---

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

```bash

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

```bash
$ omarchy theme
$ omarchy colors

```

Both resolve to the same underlying command.

Inspect metadata for a specific command:

```bash
$ omarchy commands --metadata theme-set

```

Override aliases in a customized fork:

```bash

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

```

Validate all metadata and aliases:

```bash
$ 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`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/menu-test.sh)** – Test suite confirming that aliases are correctly normalized and matched in the menu system.
- **[`docs/menu.md`](https://github.com/basecamp/omarchy/blob/main/docs/menu.md)** – Documentation of the menu schema, including the `aliases` field for menu items.
- **[`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/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.