How the Omarchy CLI Router Works: Longest-Prefix Routing in Bash

The Omarchy CLI router is a single Bash script that discovers omarchy-* executables in its directory, registers each as a command with metadata-driven routing, and resolves user arguments using a longest-prefix algorithm.

The Omarchy CLI router powers the omarchy command by dynamically discovering subcommands, parsing embedded metadata, and dispatching to the correct executable. Unlike typical CLI frameworks that use static mappings, Omarchy implements a lightweight, self-documenting routing system entirely in Bash. This article explains the routing mechanism, command registration, resolution strategies, and error handling based on the source code in the omacom/omarchy repository.

Command Discovery and Registration

The router scans the bin/ directory for every executable matching the pattern omarchy-* and extracts configuration from comment headers.

Metadata Parsing

Each command file is inspected for special comment lines in its first 80 lines. Lines formatted as # omarchy:key=value declare metadata properties:

# omarchy:group=theme

# omarchy:name=set

# omarchy:summary=Apply a color theme

# omarchy:alias=apply

In bin/omarchy, the function load_commands (lines 44–104) parses these declarations and builds internal lookup tables.

Dual Route Registration

Every command registers two routes:

1. Canonical route — built from group and name metadata values
2. Filename route — derived by splitting the filename on hyphens

The filename-to-route transformation (lines 53–62) converts omarchy-theme-set into omarchy theme set by using the first hyphen segment as the group and remaining segments as the name.

Aliases register additional routes flagged with IS_ALIAS=true. When collisions occur (two routes pointing to different binaries), the first registration wins and conflicts are logged for later diagnosis via omarchy commands --check (lines 56–60).

Fast-Path Resolution: Direct Binary Execution

For performance, the router attempts direct binary mapping before loading full metadata. Given arguments like theme set dracula, it constructs:

route="omarchy theme set"
binary="omarchy-theme-set"

If bin/omarchy-theme-set exists, the router immediately execs it with remaining arguments (lines 97–107). This bypasses all metadata parsing and route table lookups, making common commands like omarchy theme set execute with minimal overhead.

Fallback Resolution: Longest-Prefix Matching

When no direct binary matches, the router falls back to metadata-driven resolution:

1. Loads all command metadata via load_commands
2. Searches ROUTE_TO_KEY table for the longest matching prefix
3. Drops trailing words from the argument list until a registered route is found (lines 118–130)

This longest-prefix algorithm enables flexible command structures. A command registered as omarchy theme will match omarchy theme set dracula, with set dracula passed as arguments to the omarchy-theme binary.

Help Handling and Argument Guarding

The Omarchy CLI router provides sophisticated help and validation features.

Automatic Help Detection

Any --help or -h flag in the remaining arguments (not consumed by prefix matching) triggers help display instead of command execution (remaining_has_help_flag). The --json flag modifies output format:

# JSON-formatted help

omarchy theme list --help --json

Required Argument Validation

Commands declare required arguments via the args metadata key. When invoked without sufficient arguments, the router displays usage rather than executing the binary (lines 81–89):

omarchy theme set

# → prints usage (missing required theme name argument)

Group-Level Help

Supplying only a group name (e.g., omarchy theme) triggers synthesized group help. The router looks up the group description in GROUP_DESCRIPTIONS (defined lines 27–38) and lists all commands in that group (lines 1078–1085).

Hidden Commands and Error Recovery

Production CLIs need escape hatches and diagnostic tools.

Hidden Command Support

Commands marked # omarchy:hidden=true remain invocable but are excluded from omarchy commands listings and group help. This enables internal or experimental commands without cluttering the public interface.

Collision Detection

Route collisions—where two different binaries claim the same route—are recorded during registration. Run omarchy commands --check to audit the routing table and identify conflicts (lines 56–60).

Command Suggestions

When resolution fails, the router suggests the nearest matching command via suggest_command (lines 133–145). It uses prefix similarity to generate hints:

omarchy tme

# Unknown Omarchy command: omarchy tme

# Did you mean: omarchy theme ?

Practical Examples

These patterns demonstrate the Omarchy CLI router's behavior:

# Fast-path: direct binary execution

omarchy theme set dracula

# Help anywhere in argument list triggers usage

omarchy update aur --help

# Pass arguments after -- without parsing

omarchy theme set -- --some-weird-theme-name

# Missing required arguments blocks execution

omarchy config get

# → shows usage rather than erroring in the binary

Summary

• Single-file architecture: The entire router lives in bin/omarchy, a self-contained Bash script
• Dual registration: Commands register both canonical (metadata) and filename-derived routes
• Performance optimization: Fast-path resolution bypasses metadata parsing for direct binary matches
• Flexible matching: Longest-prefix algorithm handles nested subcommand structures
• Self-documenting: Embedded metadata drives help generation, argument validation, and command discovery
• Developer tooling: Hidden commands, collision detection, and suggestions support complex CLI ecosystems

Frequently Asked Questions

How does Omarchy find available commands?

The router scans its own directory (bin/) for executables matching omarchy-*. It parses the first 80 lines of each file for # omarchy:key=value metadata comments, then registers routes based on declared group and name values or filename-derived fallbacks.

What happens when two commands define the same route?

The first registration wins. Subsequent collisions are recorded in an internal table and can be reported using omarchy commands --check. This design prioritizes startup speed over strict validation while still enabling diagnostic visibility.

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

Due to longest-prefix matching, omarchy theme is the registered route and set --help becomes the remaining arguments. The --help flag in remaining arguments triggers help for the resolved command (theme), not for a hypothetical subcommand. This is intentional behavior in bin/omarchy lines 118–130.

How can I hide a command from omarchy commands listings?

Add # omarchy:hidden=true to the command's metadata header. The command remains fully functional and invocable, but is excluded from generated help and group listings.

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