# How Omarchy's CLI Router Handles Longest-Prefix Matching

> Discover how Omarchy's CLI router performs longest-prefix matching to efficiently resolve commands. Learn about its argument matching and fallback logic for precise command execution.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: internals
- Published: 2026-09-03

---

**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/main/docs/cli-router.md)](https://github.com/omacom/omarchy/blob/quattro/docs/cli-router.md#L49):

```text
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](https://github.com/omacom/omarchy/blob/quattro/docs/cli-router.md#L86):

```text
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

```bash

# 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/main/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](https://github.com/omacom/omarchy/blob/quattro/docs/cli-router.md#L49-L86)) |
| [`bin/omarchy`](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy) | Main router entry point implementing prefix discovery and delegation |
| [`bin/omarchy-*`](https://github.com/omacom/omarchy/tree/quattro/bin) | Prefix-indexed command binaries discovered by the router |
| [`test/cli`](https://github.com/omacom/omarchy/tree/quattro/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/main/docs/cli-router.md)](https://github.com/omacom/omarchy/blob/quattro/docs/cli-router.md) with behavior definitions at [line 49](https://github.com/omacom/omarchy/blob/quattro/docs/cli-router.md#L49) and [line 86](https://github.com/omacom/omarchy/blob/quattro/docs/cli-router.md#L86)
- Successful prefix matches without exact subcommands trigger **prefix listings** for command discovery
- The main router binary at [`bin/omarchy`](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy) executes this logic against [`bin/omarchy-*`](https://github.com/omacom/omarchy/tree/quattro/bin) 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`](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy) shell script, which glob-matches argument combinations against `bin/omarchy-*` files and executes the longest matching binary or generates listings accordingly.