# Longest-Prefix Matching in Omarchy CLI Resolution: How Commands Are Routed

> Discover how Omarchy CLI resolution uses longest-prefix matching to route commands. Understand argument parsing and command selection for efficient CLI design.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: deep-dive
- Published: 2026-08-27

---

**Longest-prefix matching in Omarchy’s CLI resolution algorithm selects the command with the longest matching initial segment of the argument list, passing any remaining tokens as arguments to that command.**

Omarchy’s command-line interface uses a longest-prefix matching strategy to resolve ambiguous inputs and support hierarchical command structures. This routing mechanism, implemented in the `basecamp/omarchy` repository, examines the full argument array from longest to shortest until it locates a registered command. Understanding this resolution logic is essential for developers extending Omarchy’s CLI or debugging command routing behavior.

## How the Longest-Prefix Algorithm Works

According to the [`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md) reference file, the router implements a three-phase resolution strategy:

1. **Collect the full argument list** – When `omarchy` is invoked, every token following the binary name is gathered into an array for evaluation.

2. **Iterate from longest to shortest** – The router first treats the entire argument list as a potential command name. If no exact match exists, it removes the last token and retries, continuing this progressive shortening until it finds a registered command.

3. **Execute with remaining tokens** – Once identified, the matched command receives the unconsumed portion of the argument list—the tokens not used in the matching step—as its own arguments.

This approach ensures that when multiple commands share a common prefix, the one with the longer name wins the resolution.

## Longest-Prefix Matching Examples

The following examples demonstrate how `bin/omarchy` resolves different input patterns against registered commands:

```bash

# Example 1: Exact multi-word match

$ omarchy theme set dark

# "theme set" is the longest prefix that exists,

# so that command runs with "dark" as its argument.

```

```bash

# Example 2: Longest prefix takes precedence

$ omarchy toggle wifi

# Both "toggle" and "toggle wifi" are valid prefixes,

# but "toggle wifi" is longer, so that specific command is chosen.

```

```bash

# Example 3: Fallback to shorter prefix

$ omarchy status

# No multi-word command matches "status",

# so the router falls back to the single-word command "status".

```

## Key Implementation Files

The longest-prefix matching behavior is distributed across documentation and executable scripts in the repository.

### Documentation Reference

The algorithm’s design rationale and resolution rules are specified in [`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md). This file describes how the router progressively shortens the argument array to locate valid command matches.

### Entry Point Script

The `bin/omarchy` script serves as the CLI entry point that implements the router logic. This file contains the argument parsing and prefix-selection mechanism that orchestrates command invocation by testing progressively shorter prefixes against the registry of available commands.

### Command Registration Examples

Individual commands such as `bin/omarchy-launch-about` participate in this matching scheme, registering themselves as endpoints within the longest-prefix resolution tree. These scripts demonstrate how executable files integrate with the hierarchical command structure.

## Summary

- Omarchy uses **longest-prefix matching** to resolve inputs by testing the full argument list first, then progressively shortening until finding a match.
- The algorithm prioritizes longer command names over shorter prefixes when both are valid candidates for the input.
- Remaining arguments after the matched prefix are forwarded as parameters to the selected command.
- Implementation spans [`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md) for specification and `bin/omarchy` for the routing execution logic.

## Frequently Asked Questions

### What happens if two commands share the same prefix length?

When two commands have identical prefix lengths, the exact match against the longest possible candidate wins. The router evaluates the argument array against all registered commands, selecting only the one that matches the longest initial segment of the input.

### How does Omarchy handle arguments after the matched prefix?

The router splits the input array at the boundary of the matched prefix. Tokens consumed during the matching process identify the command, while the remaining tokens are passed as arguments to that command’s implementation.

### Where is the longest-prefix matching algorithm documented?

According to the `basecamp/omarchy` source code, the resolution algorithm is documented in [`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md), which details the progressive shortening strategy and design rationale for the CLI router.

### Can commands be nested multiple levels deep with this system?

Yes, the longest-prefix mechanism supports arbitrary nesting depths. Commands like `omarchy theme set dark` demonstrate three-level hierarchies where intermediate segments participate in the matching process, allowing complex subcommand structures without explicit delimiter requirements.