How Omarchy's CLI Routing System Works Internally: A Deep Dive into the Dispatcher

Omarchy's CLI uses a two-stage dispatch mechanism where the bin/omarchy dispatcher first attempts a fast filename match against omarchy-* binaries, then falls back to a full metadata-driven route table lookup built from header comments in each executable.

The Omarchy command-line interface follows a unique convention-driven architecture that transforms filenames into command hierarchies. Located in the basecamp/omarchy repository, the routing system treats every executable matching the omarchy-* pattern as a potential command, parsing metadata from the first 80 lines of each file to build a dynamic route table. This design enables zero-configuration command discovery while maintaining low-latency dispatch through intelligent caching strategies.

Binary-to-Route Mapping and Filename Conventions

The routing system in bin/omarchy treats every executable file prefixed with omarchy- as a command candidate. The dispatcher derives routes by splitting the filename at hyphens to establish command groups and names.

When processing a filename like omarchy-theme-set, the dispatcher splits at the first hyphen to obtain group theme and name set. Remaining hyphens become spaces, so omarchy-hw-asus-rog maps to the route omarchy hw asus rog. A binary without extra hyphens, such as omarchy-update, becomes the root command of its own group with an empty name.

Each binary registers two distinct routes:

• Canonical route: The processed route omarchy <group> <name> after applying any metadata overrides via the # omarchy:name= comment directive.

• Filename route: The route derived directly from the filename with hyphens converted to spaces.

If metadata moves the name—for example, # omarchy:name=gaming xbox-cloud embedded in omarchy-install-gaming-xbox-cloud—both the canonical route (omarchy install gaming xbox-cloud) and the original filename route (omarchy install gaming xbox cloud) resolve to the same binary. An explicit empty name (# omarchy:name=) designates the command as the group's root, allowing omarchy-menu-share to resolve as omarchy share.

Metadata Extraction from Command Headers

The register_command function in bin/omarchy (source lines 87-104) scans only the first 80 comment lines of each binary to extract routing metadata. This keeps the startup sequence fast while allowing rich command definitions.

Recognized metadata keys include:

• group – Overrides the default group derived from the filename.
• name – Overrides the default name or creates multi-word command names.
• summary – Brief description shown in help listings.
• args – Argument specification for validation.
• examples – Usage examples displayed in help text.
• alias or aliases – Additional routes that resolve to this command.
• requires-sudo – Indicates if the command needs elevated privileges.
• hidden – Excludes the command from standard listings unless --all is used.

If no metadata is present, the system derives defaults strictly from the filename. Missing or malformed metadata is silently ignored, falling back to the filename route without breaking the dispatch chain.

Route Table Construction

During initialization, the load_commands function iterates over all omarchy-* executables in the path, invoking register_command for each binary. This process populates several associative arrays that form the complete routing infrastructure:

• COMMAND_ROUTE – Stores the canonical route for each command.
• COMMAND_FALLBACK_ROUTE – Stores the raw filename-derived route.
• COMMAND_BINARY – Maps commands to their filesystem paths.
• COMMAND_GROUP, COMMAND_NAME, COMMAND_SUMMARY – Store parsed metadata.
• ROUTE_TO_KEY – Primary lookup table mapping route strings to command keys.
• ROUTE_IS_ALIAS – Marks routes that function as aliases.
• ROUTE_COLLISIONS – Tracks when multiple binaries claim the same route (first registration wins).

This approach ensures that the ROUTE_TO_KEY table contains every valid path for command resolution, including aliases and fallback routes, enabling both exact matches and prefix-based lookups.

The Two-Stage Dispatch Algorithm

The dispatcher implements two distinct resolution paths to balance speed against flexibility.

Fast Path: Direct Filename Resolution

The dispatch_fast_or_help function provides the hot path for command execution. It calls resolve_direct_route to build candidate filenames by joining input arguments with hyphens and checking for executable files.

For example, when executing omarchy theme set dark, the resolver checks for bin/omarchy-theme-set-dark, then bin/omarchy-theme-set. If found, the remaining arguments (dark) are passed directly to the binary.

This path avoids loading any metadata, requiring only a few stat calls. It also handles help flags intelligently: if any remaining token is --help or -h, or if command_requires_args detects missing required arguments, the router loads the command's metadata and displays help instead of executing.

Full Path: Metadata-Driven Resolution

If the fast path fails to locate a binary, the router invokes dispatch_or_help, which loads all command metadata via load_commands and uses resolve_route to perform a longest-prefix match against the ROUTE_TO_KEY table.

Once resolved, the system performs the same validation checks as the fast path using remaining_has_help_flag and command_requires_args. If validation passes, the dispatcher executes the binary via exec, replacing the shell process entirely. On failure, suggest_command provides typo correction by inspecting the route table for similar entries.

Help System and Introspection

The routing system exposes its internal state through several introspection commands that draw directly from the route table:

• omarchy commands – Lists every non-hidden command using the COMMAND_SUMMARY array.
• omarchy commands --all – Includes hidden commands in the output.
• omarchy commands --json – Emits machine-readable JSON arrays of command records.
• omarchy commands --markdown – Generates documentation-friendly output.
• omarchy commands --check – Validates metadata consistency across all binaries.

The top-level help interface, implemented in show_main_help, organizes commands by group using the GROUP_DESCRIPTIONS associative array defined in bin/omarchy. Because all help text pulls from the route table constructed at startup, documentation automatically reflects the current set of installed binaries without regeneration steps.

Code Examples in Practice

The following examples demonstrate the routing behavior:

# Fast path: direct filename match

$ omarchy theme set dark

# → Executes bin/omarchy-theme-set with argument "dark"

# Canonical route with metadata override

# File: bin/omarchy-install-gaming-xbox-cloud contains:

#   # omarchy:name=gaming xbox-cloud

$ omarchy install gaming xbox-cloud

# → Executes bin/omarchy-install-gaming-xbox-cloud via canonical route

# Help interception without execution

$ omarchy theme set --help

# → Loads metadata and displays summary/usage information

# JSON introspection of the route table

$ omarchy commands --json

# → Outputs structured data including routes, summaries, and binary paths

Summary

• Filename convention: Commands follow the omarchy-* pattern, with hyphens delimiting groups and subcommands.
• Dual registration: Each binary registers both a canonical route (metadata-driven) and a fallback route (filename-driven).
• Metadata scope: Only the first 80 lines are parsed for directives like name, group, alias, and requires-sudo via the register_command function.
• Fast dispatch: The dispatch_fast_or_help path checks filesystem existence before loading any metadata, minimizing latency for common commands.
• Full resolution: The dispatch_or_help path builds a complete route table in ROUTE_TO_KEY for prefix matching and alias support.
• Dynamic help: All help output, including omarchy commands --json, reflects the live state of the bin/ directory.

Frequently Asked Questions

How does Omarchy map filenames to CLI routes?

Omarchy splits the filename after the omarchy- prefix at the first hyphen to determine the group and name. Additional hyphens become spaces in the route. For example, omarchy-hw-asus-rog becomes the route omarchy hw asus rog. The register_command function in bin/omarchy (lines 87-104) handles this parsing while checking for metadata overrides.

What metadata keys does Omarchy support in command headers?

The scanner recognizes group, name, summary, args, examples, alias, aliases, requires-sudo, and hidden. These are extracted from comment lines (starting with #) within the first 80 lines of the binary. If unspecified, the system derives group and name from the filename pattern.

Why does Omarchy use a two-stage dispatch algorithm?

The two-stage design optimizes for the common case where the command exists as a simple filename match. The dispatch_fast_or_help function checks filesystem existence without parsing metadata, executing in milliseconds. Only when this fails does the system incur the cost of building the full route table via load_commands and resolve_route, ensuring expensive operations occur only when necessary.

How can I override the default route generated from a filename?

Add a metadata comment specifying # omarchy:name= followed by your desired route segments separated by spaces. For example, placing # omarchy:name=gaming xbox-cloud in a file named omarchy-install-gaming-xbox-cloud makes omarchy install gaming xbox-cloud the canonical route while preserving the original filename route as an alias. To make a command the root of its group, use # omarchy:name= with an empty value.

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