# How Routing Metadata Is Extracted from Omarchy CLI Binaries: A Deep Dive into the Self-Documenting Router

> Discover how Omarchy extracts routing metadata from CLI binaries by scanning structured comments and filenames. Learn about this self-documenting router for basecamp/omarchy.

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

---

**Omarchy extracts routing metadata by scanning the first 80 lines of each `bin/omarchy-*` executable for structured comments matching the pattern `# omarchy:key=value`, falling back to filename parsing when metadata is absent.**

The Omarchy CLI uses a lightweight, self-documenting router implemented in `bin/omarchy` that eliminates the need for a central registry file. By parsing command metadata directly from executable headers, the system allows developers to add, rename, or hide commands simply by editing comment blocks in individual binary files. Understanding how routing metadata is extracted from Omarchy CLI binaries reveals an elegant balance between convention-based defaults and explicit configuration.

## Discovering Available Commands

The routing process begins when the `load_commands` function (lines 15‑18 of `bin/omarchy`) iterates over every file matching the pattern `bin/omarchy-*`. For each executable found, the router immediately calls `register_command` to process its metadata header.

This discovery mechanism assumes that all valid subcommands follow the naming convention `omarchy-{group}-{name}`. The router dynamically builds its command table at runtime, ensuring that newly added binaries become available without restarting the shell or updating a separate manifest.

## Scanning File Headers for Metadata

Inside `register_command`, the router implements a conservative scanning strategy to balance performance with flexibility. The script reads only the first **80 lines** of each file, defined by the constant `METADATA_SCAN_LIMIT`.

The scanner stops immediately upon encountering any non-comment line, guaranteeing that only the initial comment block at the top of the file is considered. This early-exit behavior (implemented between lines 87‑100 of `bin/omarchy`) prevents the router from parsing large binaries or scripts with extensive implementation code.

### The Metadata Regex Pattern

Each comment line is tested against the following POSIX-compliant regular expression:

```bash
^[[:space:]]*#\s*omarchy:([[:alnum:]_-]+)=(.*)$

```

Lines matching this pattern are parsed into **key** and **value** pairs (lines 202‑207). Recognized metadata keys include:

- **group**: The command category (e.g., `theme`, `hw`)
- **name**: The specific action within the group
- **summary**: Human-readable description
- **args**: Argument specification syntax
- **examples**: Usage examples
- **alias** or **aliases**: Alternative invocation paths
- **requires-sudo**: Boolean flag for elevated privileges
- **hidden**: Boolean flag to suppress from help listings

Unrecognized keys are silently ignored (line 238), allowing forward compatibility with future metadata extensions.

## Fallback Mechanisms and Default Inference

When explicit metadata is missing, the Omarchy router derives defaults from the binary filename itself, ensuring that even minimal scripts integrate seamlessly into the CLI.

### Filename-Based Defaults

If no `omarchy:summary` comment is found, the router captures the first plain comment line (starting with `#`) as a fallback summary (lines 240‑248). For the command structure, the stem after the `omarchy-` prefix undergoes the following transformation (lines 56‑60):

1. Split at the **first hyphen** to separate **group** from **name**
2. Convert remaining hyphens to spaces (e.g., `omarchy-hw-asus-rog` → group `hw`, name `asus rog`)
3. If no hyphen exists, the entire stem becomes the group with an empty name (line 17)

This convention-over-configuration approach ensures that a binary named `bin/omarchy-update` automatically registers as the command `omarchy update` without requiring any header comments.

## Building and Registering Routes

Once metadata is extracted or inferred, the router constructs canonical routes. The primary route follows the format `omarchy <group> <name>` (lines 66‑70), while a fallback route uses the filename with every hyphen converted to a space.

Both routes are registered via `register_route` (lines 95‑99) and stored in associative arrays including `COMMAND_ROUTE`, `COMMAND_GROUP`, and `COMMAND_SUMMARY` (lines 80‑94). This hash-based storage enables O(1) lookup during command dispatch.

### Handling Aliases

The router supports multiple aliases through the `alias` or `aliases` keys. Values are split on the pipe character (`|`), and each segment registers as an alternative route flagged as an alias (lines 100‑108). This allows users to invoke the same binary through intuitive shortcuts without duplicating files.

## Dispatch and Execution

When a user runs `omarchy <tokens>`, the router first attempts a fast-path filename probe (e.g., checking for `bin/omarchy-theme-set-foo`). If this fails, the system consults the pre-built metadata tables to resolve the longest-prefix matching route, as detailed in [`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md).

The combination of static filename conventions and dynamic comment-based metadata enables Omarchy to maintain a discoverable, self-documenting CLI interface without centralized configuration files.

## Practical Implementation Examples

### Example 1: Explicit Metadata Declaration

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

# omarchy:group=theme

# omarchy:name=set

# omarchy:summary=Set the active Omarchy theme

# omarchy:args=[theme-name]

# omarchy:requires-sudo=true

# omarchy:hidden=false

# Implementation follows...

```

Running `omarchy theme set solarized` resolves to this binary because the header explicitly defines the group and name, while the router passes `solarized` as the remaining argument.

### Example 2: Command Aliases

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

# omarchy:summary=Take a screenshot

# omarchy:aliases=omarchy capture screenshot|omarchy screen snap

# Screenshot implementation...

```

The router registers both the canonical route and the two aliases. Users may invoke `omarchy screen snap`, which dispatches to the same underlying binary as `omarchy capture screenshot`.

### Example 3: Implicit Convention

A file named `bin/omarchy-update` containing **no** metadata comments automatically registers with:
- **Group**: `update`
- **Name**: *(empty)*
- **Summary**: `Run the update command`
- **Route**: `omarchy update`

This demonstrates how Omarchy achieves zero-configuration routing for simple utilities.

## Summary

- **Omarchy scans the first 80 lines** (`METADATA_SCAN_LIMIT`) of each `bin/omarchy-*` executable, stopping at the first non-comment line to locate metadata.
- **Metadata follows the pattern** `# omarchy:key=value`, supporting keys like `group`, `name`, `summary`, `alias(es)`, `requires-sudo`, and `hidden`.

- **Filename conventions provide defaults**: The stem after `omarchy-` is split on the first hyphen to derive group and name, with remaining hyphens converted to spaces.
- **Associative arrays** (`COMMAND_ROUTE`, `COMMAND_GROUP`, etc.) store extracted data for fast O(1) dispatch lookups.
- **Aliases are pipe-delimited** in the `aliases` key and registered as alternative routes to the same binary.
- **Comprehensive fallbacks** ensure that even binaries without header comments integrate correctly into the CLI hierarchy.

## Frequently Asked Questions

### What is the maximum number of lines scanned for metadata in Omarchy?

The router limits header scanning to **80 lines** per executable, controlled by the `METADATA_SCAN_LIMIT` constant in `bin/omarchy`. This constraint ensures efficient startup performance even when command binaries are large scripts. The scanner also implements early termination upon encountering the first non-comment line, often exiting long before reaching the 80-line threshold.

### How does Omarchy handle commands without explicit metadata comments?

When a binary lacks structured `# omarchy:` comments, the router derives metadata from the filename itself. According to lines 56‑60 of `bin/omarchy`, the stem following the `omarchy-` prefix is split at the first hyphen to determine the **group** and **name**, while hyphens in the remainder become spaces. If no summary is provided via metadata, the system captures the first plain comment line or generates a default description.

### What regex pattern does the Omarchy router use to parse metadata?

The router uses the POSIX-compliant pattern `^[[:space:]]*#\s*omarchy:([[:alnum:]_-]+)=(.*)$` to identify valid metadata lines. This regex extracts the key (alphanumeric with hyphens/underscores) and value from comment lines, as implemented in lines 202‑207 of `bin/omarchy`. Lines not matching this pattern are ignored unless they are plain comments eligible for fallback summary extraction.

### Can a single Omarchy command have multiple aliases?

Yes, Omarchy supports multiple aliases through the `alias` or `aliases` metadata keys. Values are split on the pipe character (`|`), and each segment registers as a distinct route pointing to the same executable (lines 100‑108). For example, the value `omarchy capture screenshot|omarchy screen snap` creates two valid invocation paths for one binary, improving discoverability without code duplication.