How Omarchy CLI Command Center Routing Works: A Deep Dive into the Bash Router

Omarchy's CLI command center uses a pure-Bash router that dynamically discovers executables in bin/, parses structured metadata from comment headers, and dispatches user requests to the appropriate binary via fast associative-array lookups.

Omarchy's command-line interface eliminates hardcoded command lists by implementing a self-discovering routing system. According to the omacom/omarchy source code, the central router in bin/omarchy builds a lightweight command registry at runtime, parsing special # @omarchy: metadata blocks to automatically generate help text and resolve routes.

Phase 1: Loading and Registering Commands

The routing process begins when the load_commands function scans every file in $OMARCHY_BIN_DIR (typically bin/), excluding the router itself.

Scanning bin/ and Parsing Metadata

For each executable discovered, the router invokes register_command (lines 168-190 in bin/omarchy). This function reads the first 80 lines of the file (defined by the constant METADATA_SCAN_LIMIT) searching for comment lines starting with # @omarchy:.

The parser extracts these metadata fields:

• group – Logical categorization for help organization
• name – Short command identifier
• summary – One-line description
• usage – Full syntax string including positional arguments
• args – Argument placeholders
• examples – Pipe-separated usage examples
• aliases – Alternative command names
• requires_sudo – Elevation requirements flag
• hidden – Visibility in default command listings

After extraction, the function populates associative arrays including COMMAND_ROUTE, COMMAND_GROUP, and COMMAND_USAGE.

Route Registration

Once metadata is parsed, register_route (lines 150-166) maps the textual route (e.g., theme set) to an internal key in the ROUTE_TO_KEY array. The system enforces route uniqueness; duplicate routes are recorded in ROUTE_COLLISIONS for debugging.

Phase 2: Resolving the Request

When a user executes omarchy <tokens...>, control passes to dispatch_fast_or_help (lines 887-904).

Fast Route Resolution

The router first attempts resolve_fast_route, which performs a longest-prefix match against the ROUTE_TO_KEY associative array. It walks the token list sequentially, checking for valid route matches at each depth.

If the resolved route points to a concrete binary, resolve_binary locates the executable path. If the route resolves only to a group (e.g., omarchy theme without a subcommand), the system invokes show_group_help to display categorized available commands.

Global Flag Detection

Before execution, the router inspects remaining arguments using remaining_has_help_flag and remaining_has_json_flag (lines 128-146). These helpers detect --help, -h, and --json flags early, ensuring they pass through to the target binary unchanged for native handling.

Phase 3: Execution or Fallback

Binary Execution

When a valid binary is resolved, the router executes:

exec "$binary_path" "${remaining[@]}"

This replaces the current process with the target command, forwarding any unparsed arguments directly.

Unknown Command Handling

If resolve_fast_route fails to find a match, the router prints "Unknown Omarchy command" and invokes suggest_command (lines 610-671). This fuzzy matching algorithm compares the input against known command keys to suggest the closest alternative. The process exits with status 127 to indicate command not found, prompting users to run omarchy commands --all for discovery.

Metadata Format for Command Authors

To participate in the routing system, command scripts must include metadata headers:

#!/bin/bash

# @omarchy: group=theme

# @omarchy: name=set

# @omarchy: summary=Apply a theme to Omarchy

# @omarchy: usage=omarchy theme set <theme-name>

# @omarchy: args=<theme-name>

# @omarchy: examples=omarchy theme set dracula|omarchy theme set nord

# @omarchy: hidden=false

The router discovers this automatically when load_commands runs, requiring no modifications to the central router code when adding new functionality.

Summary

• Omarchy's CLI uses a pure-Bash router located in bin/omarchy that discovers commands dynamically from the bin/ directory.

• Metadata-driven registration parses # @omarchy: comments to populate associative arrays like COMMAND_ROUTE and COMMAND_GROUP.

• Fast resolution uses resolve_fast_route to match the longest valid prefix against the ROUTE_TO_KEY registry.

• Transparent flag passing ensures --help and --json flags reach target binaries for native processing.

• Fuzzy fallback via suggest_command provides intelligent suggestions when users mistype commands, exiting with code 127.

Frequently Asked Questions

How does Omarchy discover new commands without modifying the router?

The load_commands function scans the bin/ directory at runtime, automatically registering any executable containing valid # @omarchy: metadata headers. This allows developers to add commands simply by placing new scripts in the directory without touching the central router logic in bin/omarchy.

What happens when I type an incomplete command like omarchy theme?

The router resolves theme as a group route without a concrete binary, triggering show_group_help to display all available subcommands within that group, such as theme set or theme list.

Why does the router use exec instead of spawning a subprocess?

The dispatch_fast_or_help function uses exec "$binary_path" "${remaining[@]}" to replace the current shell process with the target binary. This eliminates overhead, ensures signals propagate correctly, and preserves exit codes while forwarding all remaining arguments untouched.

How does the suggestion algorithm work for misspelled commands?

When resolve_fast_route fails, the suggest_command function (located around lines 610-671) performs fuzzy string matching against registered command keys in the associative arrays. It calculates similarity between the input tokens and known routes, offering the closest match before exiting with status 127.

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