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

> Discover how the Omarchy CLI router uses longest-prefix routing in Bash to manage omarchy-* executables with metadata-driven commands. Streamline your command line experience.

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

---

**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](https://github.com/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:

```bash

# 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:

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

```

If `bin/omarchy-theme-set` exists, the router immediately `exec`s 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:

```bash

# 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):

```bash
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:

```bash
omarchy tme

# Unknown Omarchy command: omarchy tme

# Did you mean: omarchy theme ?

```

## Practical Examples

These patterns demonstrate the Omarchy CLI router's behavior:

```bash

# 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.