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

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:

^[[: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.

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

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

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

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