How the Omarchy CLI Router Resolves Commands: A Technical Deep Dive

The Omarchy CLI router resolves commands by performing longest-prefix matching against binaries in bin/, extracting metadata from leading comments, and dispatching matched executables via exec while falling back to help text or prefix listings when no exact match exists.

The basecamp/omarchy repository implements a lightweight yet sophisticated command-line interface through its central router script located at bin/omarchy. This router serves as the primary dispatcher for the omarchy command, transforming user arguments into executable instructions through a deterministic resolution algorithm. Understanding this routing mechanism is essential for extending Omarchy with custom commands or integrating its CLI into automation workflows.

Longest-Prefix Matching Algorithm

At the core of Omarchy's command resolution lies a longest-prefix matching strategy that prioritizes specific matches over general ones. When a user invokes omarchy with arguments, the router attempts to match the complete argument list against available routes before progressively shortening the prefix.

Progressive Argument Evaluation

According to the implementation documented in docs/cli-router.md (lines 49-52), the router first attempts to match the full argument list against the filesystem. If no binary exists for that specific path, the router removes the last argument and retries with the shortened prefix. This process continues until either a match is found or the argument list is exhausted, ensuring that complex subcommands like omarchy theme set resolve correctly before falling back to simpler omarchy theme commands.

Metadata Extraction from Binaries

Each executable binary in the bin/ directory may contain a leading comment line that provides descriptive metadata. As specified in docs/cli-router.md (lines 43-44), the router extracts comments formatted as # omarchy:summary=<description> to generate help text and provide command summaries. This convention allows the router to build dynamic help menus without requiring a separate configuration file.

Alias Resolution Strategy

The Omarchy CLI router handles command aliases through a two-tier lookup mechanism that balances direct execution with flexible naming conventions.

Direct Binary Matching

When resolving a command such as omarchy screenshot, the router first searches for a binary named exactly omarchy-screenshot in the bin/ directory. If this direct match exists, the router immediately prepares it for execution without additional processing.

Alias Table Fallback

If no direct binary match exists, the router consults its internal alias mapping. As detailed in docs/cli-router.md (lines 63-66), aliases like screenshot map to specific command groups (e.g., omarchy-capture-screenshot). The router loads the entire route set and resolves the alias to the appropriate executable, enabling shorter command names without duplicating binaries.

Command Dispatch and Execution

Once the router identifies a concrete route, it employs a direct execution model that replaces the routing process entirely.

The Exec Dispatch Mechanism

The router uses the exec builtin to transform the current process into the target binary. As implemented in docs/cli-router.md (lines 82-84), the router constructs the command:

exec "$binary" "${remaining_args[@]}"

This approach ensures that the target binary receives only the arguments following its resolved name, and the exit code returned to the shell originates directly from the executed command rather than the router itself.

Help Fallback Behavior

When invoked without arguments, the router displays a global help overview instead of attempting execution. This behavior, documented at lines 78-80 of docs/cli-router.md, lists available commands using their extracted metadata summaries, providing immediate orientation for new users.

Prefix Listing Mode

If the router cannot resolve the provided arguments to any known route, it enters a prefix-listing mode. According to docs/cli-router.md (lines 86-88), the system displays valid subcommands that share the given prefix. For example, invoking omarchy hw might list omarchy hw asus and omarchy hw intel as available continuations, guiding users toward valid syntax interactively.

Machine-Readable Route Discovery

For integration with external tooling and automation scripts, the Omarchy CLI router supports structured output formats.

JSON Route Export

Adding the --json flag to the base omarchy command causes the router to emit a complete JSON description of every available route. As specified in docs/cli-router.md (lines 130-132), this output includes command paths, metadata summaries, and binary locations, enabling programmatic discovery without parsing human-readable help text.

Practical Examples

The following examples demonstrate the Omarchy CLI router's resolution behavior in practice:

# Longest-prefix matching executes `omarchy-theme-set` with "dark" as argument

omarchy theme set dark

# Alias resolution maps `screenshot` to `omarchy-capture-screenshot`

omarchy screenshot

# No arguments triggers help fallback

omarchy

# Unknown prefix triggers listing of valid `hw` subcommands

omarchy hw unknown

# Machine-readable route dump for tooling

omarchy --json

Summary

• The Omarchy CLI router in bin/omarchy implements longest-prefix matching to resolve complex subcommands before falling back to simpler prefixes.

• Command metadata derives from # omarchy:summary= comments within binary files, eliminating the need for external configuration.

• Alias resolution first attempts direct binary matching, then consults an internal mapping table for flexible command naming.

• The router uses exec to replace itself with the target binary, ensuring accurate argument passing and exit code propagation.

• Fallback mechanisms include global help display (no arguments) and prefix listing (unknown commands) to guide user interaction.

• The --json flag enables machine-readable route discovery for automation and integration tasks.

Frequently Asked Questions

How does the Omarchy CLI router handle unknown commands?

When the router encounters arguments that match no known route, it activates prefix-listing mode. As documented in docs/cli-router.md (lines 86-88), the system displays valid subcommands that share the provided prefix, helping users identify correct syntax. For example, omarchy hw unknown would list available hardware-specific commands like omarchy hw asus or omarchy hw intel.

What is the difference between a direct binary and an alias in Omarchy?

Direct binaries exist as files named omarchy-<command> in the bin/ directory and execute immediately upon matching. Aliases, conversely, provide shorter names that map to longer binary names through the router's internal resolution table. According to docs/cli-router.md (lines 63-66), the router checks for direct matches first, then falls back to alias resolution only when no direct binary exists.

How can I list all available Omarchy commands programmatically?

Invoke omarchy --json to receive a structured JSON array containing every available route, its summary description, and binary location. This output, described in docs/cli-router.md (lines 130-132), provides machine-readable metadata suitable for building autocompletion scripts or integration dashboards without parsing shell output.

Where is the Omarchy CLI router source code located?

The primary routing logic resides in bin/omarchy, while the design specification and resolution algorithm details are documented in docs/cli-router.md. Individual commands follow the naming convention bin/omarchy-<command> and may include metadata comments that the router extracts for help generation.

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