How Omarchy's CLI Router Handles Longest-Prefix Matching

Omarchy's CLI router resolves commands by progressively matching the longest possible prefix of user arguments against available binaries, falling back to shorter prefixes when exact matches don't exist.

The Omarchy project implements a unique command-line architecture where a single entry point binary dynamically discovers and delegates to subcommand binaries. This routing mechanism relies on longest-prefix matching to determine which executable handles a given invocation. According to the Omarchy source documentation, the router's resolution strategy prioritizes specificity while maintaining graceful degradation for partial commands.

How the Longest-Prefix Algorithm Works

The router's matching process follows a deterministic, three-phase resolution path:

Full-Argument Resolution

The router first attempts to resolve the complete argument list as a concrete route. If a binary exists whose name matches omarchy-<arg1>-<arg2>-..., that binary executes immediately. As documented in [docs/cli-router.md](https://github.com/omacom/omarchy/blob/quattro/docs/cli-router.md#L49):

Resolution is longest-prefix: the router tries the full argument list as a...

This phase ensures that fully-qualified commands resolve directly without unnecessary fallback overhead.

Progressive Prefix Trimming

When the full argument list fails to match any binary, the router truncates arguments from the right and retries the lookup. This progressive shortening continues until a matching prefix is found or all arguments are exhausted. The longest valid prefix wins—hence "longest-prefix matching."

For example, invoking omarchy hw asus with no exact omarchy-hw-asus binary triggers fallback to omarchy-hw. The documentation explicitly describes this behavior at line 86:

When nothing resolves, the router tries a prefix listing — `omarchy hw asus`

Prefix Listing Display

Upon matching a prefix without an exact subcommand continuation, the router outputs a prefix listing—a dynamically generated inventory of available commands beneath that prefix. This transforms partial matches into discovery opportunities rather than errors.

Practical Command Resolution Examples

# Phase 1: Exact match — executes bin/omarchy-theme-set

omarchy theme set dark

# Phase 2: Longest-prefix fallback — no 'omarchy-hw-asus' exists,

# so router lists subcommands under 'hw asus' prefix

omarchy hw asus

# Phase 3: No matching prefix — router displays top-level help

omarchy nonexistent-command

Key Implementation Files

File	Purpose
[docs/cli-router.md](https://github.com/omacom/omarchy/blob/quattro/docs/cli-router.md)	Core documentation defining the longest-prefix resolution algorithm (lines 49–86)
bin/omarchy	Main router entry point implementing prefix discovery and delegation
bin/omarchy-*	Prefix-indexed command binaries discovered by the router
test/cli	Validation suite for prefix-matching edge cases

Architectural Benefits

The longest-prefix design delivers several operational advantages specific to Omarchy's deployment model:

• Zero-configuration extensibility — New commands appear automatically when binaries following the naming convention are added to bin/
• Intuitive discoverability — Partial commands yield navigable listings rather than opaque failures
• Hierarchical organization — Deep command structures (e.g., omarchy config network wifi setup) resolve naturally through progressive prefix matching

Summary

• Omarchy's CLI router implements longest-prefix matching by attempting full-argument resolution first, then progressively trimming rightmost arguments
• The algorithm is explicitly documented in [docs/cli-router.md](https://github.com/omacom/omarchy/blob/quattro/docs/cli-router.md) with behavior definitions at line 49 and line 86
• Successful prefix matches without exact subcommands trigger prefix listings for command discovery
• The main router binary at bin/omarchy executes this logic against bin/omarchy-* executables

Frequently Asked Questions

What happens when no prefix matches at all?

The router falls back to displaying top-level help output, showing all available command groups and their summaries. This occurs when the user's input doesn't share a prefix with any installed omarchy-* binary.

How does Omarchy distinguish between omarchy-hw and omarchy-hw-asus?

The router prefers longer prefixes. If both binaries exist, omarchy hw asus invokes omarchy-hw-asus; if only omarchy-hw exists, invocation falls back to that binary with asus treated as a subcommand argument for listing.

Can users create arbitrarily deep command hierarchies?

Yes. The prefix-matching algorithm imposes no depth limit—each additional hyphen-separated segment in the binary name extends the command hierarchy. The router handles depth through iterative argument trimming.

Where is the longest-prefix logic actually implemented?

The resolution algorithm is implemented in the main bin/omarchy shell script, which glob-matches argument combinations against bin/omarchy-* files and executes the longest matching binary or generates listings accordingly.

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