How Does the Omarchy CLI Router Work? A Deep Dive into the Bash-Based Command Router

The Omarchy CLI router is a single Bash script (bin/omarchy) that auto-discovers every omarchy-* executable in its directory, registers commands via metadata parsing, and resolves invocations using a longest-prefix matching algorithm with a fast-path execution loop.

This article explains the internal mechanics of the Omarchy command-line interface routing system, as implemented in the omacom/omarchy repository. The router enables a clean subcommand structure (omarchy theme set, omarchy update aur) without requiring each command to reimplement argument parsing or help generation.

Command Registration: Discovering and Indexing Binaries

The Omarchy CLI router begins by scanning its own directory for any executable file matching the pattern omarchy-*. Each discovered binary undergoes metadata extraction and route registration.

Metadata Extraction from Comment Headers

For every omarchy-* file found, the router reads the first 80 lines searching for metadata directives in the format # omarchy:key=value. Supported keys include group, name, summary, alias, args, and hidden (source).

# Example metadata block in bin/omarchy-theme-set:

# omarchy:group=theme

# omarchy:name=set

# omarchy:summary=Apply a color theme

# omarchy:args=THEME_NAME

Fallback Route Derivation

When metadata is absent or incomplete, the router derives a fallback route directly from the filename. It splits on the first hyphen to determine the group, then converts remaining hyphens to spaces for the name (source):

Filename	Derived Group	Derived Name
omarchy-theme-set	theme	set
omarchy-update-aur	update	aur
omarchy-commands	commands	(empty)

Route Registration and Collision Handling

Every command receives two route entries: the canonical route (after metadata overrides) and the filename-based route. Aliases create additional entries flagged as IS_ALIAS=true. When collisions occur—two different binaries registering the same route—the first registration wins and the conflict is logged for later inspection (source).

Fast-Path Resolution: Direct Binary Execution

The Omarchy CLI router prioritizes performance through a fast-path resolution mechanism that bypasses metadata lookups entirely. When arguments arrive, the router immediately constructs a candidate binary name:

route="omarchy $(join_words " " "${args[@]:0:prefix_count}")"
binary="omarchy-$(join_words "-" "${args[@]:0:prefix_count}")"

If bin/$binary exists, the router executes it directly with remaining arguments (source). This hot-path optimization ensures common commands like omarchy theme set dracula launch without metadata overhead.

Fast-Path Execution Example

# Router skips metadata, execs bin/omarchy-theme-set immediately

omarchy theme set dracula

Fallback Resolution: Longest-Prefix Matching

When no direct binary match exists, the router falls back to full metadata-driven resolution:

1. Load all command metadata via load_commands
2. Iterate through argument prefixes from longest to shortest
3. Query the ROUTE_TO_KEY associative array for a registered match (source)

This longest-prefix algorithm enables flexible command structures where partial matches resolve correctly:

# Registered: omarchy theme set

# Invoked:    omarchy theme

# Result:     Group help for 'theme' (partial match, no binary)

Help System and Argument Guarding

The Omarchy CLI router provides integrated help handling without requiring individual binaries to implement flag parsing.

Automatic Help Detection

The router scans remaining arguments for --help or -h anywhere in the command line (remaining_has_help_flag). When found, it displays the command's metadata rather than executing the binary (source).

# Help requested after subcommand argument

omarchy update aur --help

# → Shows help for 'update', not 'aur'

JSON Output Mode

Adding --json to a help request switches output to machine-readable format:

omarchy theme list --help --json

# → {"group":"theme","name":"list","summary":"..."}

Argument Validation

Commands declare required arguments via the args metadata key. When invoked without sufficient arguments, the router displays usage and exits—preventing incomplete executions:

omarchy theme set

# → Usage: omarchy theme set THEME_NAME

Group Help Generation

Invoking a group without a subcommand triggers synthesized help built from the GROUP_DESCRIPTIONS table (source):

omarchy theme

# → Lists all theme subcommands with summaries

Hidden Commands and Collision Detection

The Omarchy CLI router supports hidden commands via # omarchy:hidden=true. These commands remain invocable but exclude themselves from listings and group help.

Registered collisions are tracked throughout the registration phase. The omarchy commands --check subcommand reports any conflicts discovered, enabling debugging of route overlap during development (source).

Error Handling and Command Suggestions

When resolution fails entirely, the Omarchy CLI router provides intelligent assistance through prefix-based suggestion matching (suggest_command):

omarchy tme --help

# Output:

#   Unknown Omarchy command: omarchy tme

#   Did you mean: omarchy theme ?

#   Run 'omarchy commands --all' to discover available commands.

The suggestion algorithm finds the closest registered route by prefix similarity, reducing friction for typos and incomplete commands (source).

Flag Handling Edge Cases

The router implements POSIX-compatible flag termination with --. Everything following a bare double-dash is forwarded to the target binary unprocessed, allowing commands to receive their own flag sequences:

omarchy theme set -- --force --verbose=2

# → bin/omarchy-theme-set receives: --force --verbose=2

Practical Examples

# Fast-path execution (no metadata lookup)

omarchy theme set dracula

# Help with JSON output

omarchy config get --help --json

# Hidden command (works, but unlisted)

omarchy internal-debug logs

# Force argument passthrough

omarchy pkg search -- --regex '^vim-'

Summary

• Single-script architecture: The entire Omarchy CLI router lives in bin/omarchy, approximately 80 lines of registration logic plus resolution and help generation.

• Metadata-driven registration: Commands self-describe via # omarchy:key=value comments in their first 80 lines, enabling dynamic discovery without configuration files.

• Dual-route system: Each command registers both canonical (metadata-override) and fallback (filename-derived) routes.

• Fast-path optimization: Direct binary existence checks bypass metadata lookups for the common case.

• Longest-prefix fallback: Partial matches resolve through iterative prefix reduction against the route table.

• Integrated help system: Automatic --help/-h detection, JSON mode, and argument validation without binary cooperation.

• Developer tooling: Collision detection via omarchy commands --check and typo suggestions for unknown commands.

Frequently Asked Questions

How does the Omarchy CLI router handle command conflicts?

When two binaries register identical routes, the first registration wins and subsequent attempts are logged as collisions. Run omarchy commands --check to inspect any conflicts detected during router initialization. This design prioritizes stability—commands continue working while developers receive visibility into overlaps.

Can I override the route derived from my command's filename?

Yes. Specify # omarchy:group=VALUE and # omarchy:name=VALUE in your command's comment header. These metadata directives override the automatic fallback route while preserving the filename route as a secondary entry. Aliases (# omarchy:alias=ALTERNATE_NAME) create additional route mappings flagged separately.

What happens if I type a command that doesn't exist?

The Omarchy CLI router executes a prefix-matching suggestion algorithm (suggest_command) and displays the closest registered route with a "Did you mean?" prompt. If no reasonable match exists, it directs you to omarchy commands --all for discovery. This behavior is implemented in bin/omarchy lines 133–145.

Why does omarchy theme set --help show help for theme instead of set?

The router scans all remaining arguments for --help or -h after resolving the command prefix. In omarchy theme set --help, the longest-prefix match is omarchy theme, so the theme group's metadata is displayed. To get help for set specifically, use omarchy theme set -- --help (with -- to pass the flag through) or consult omarchy commands --all.

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