How the Omarchy CLI Router Dispatches Commands to bin/omarchy-* Binaries

The Omarchy command-line interface uses a single router script at bin/omarchy that dynamically discovers helper binaries via filesystem scanning, resolves user input through longest-prefix matching, and delegates execution via process replacement.

The Omarchy project—hosted at omacom/omarchy—implements a file-based command routing system that treats the bin/ directory as a self-documenting command registry. Unlike traditional CLI frameworks that rely on centralized switch statements, the Omarchy CLI router dynamically maps user arguments to executable binaries using naming conventions and prefix matching. This architecture enables zero-configuration extensibility: adding a new command requires only dropping a properly named executable into the bin/ folder.

Command Discovery in the bin/ Directory

The routing process begins when the main script scans the directory referenced by "$OMARCHY_PATH/bin" (or the bundled bin/ directory within the repository). The router identifies every executable file whose name starts with the omarchy- prefix and treats each as a discrete route.

The filename itself defines the command path, with hyphens representing sub-command boundaries. For example:

• bin/omarchy-theme-set registers the route theme set
• bin/omarchy-toggle-touchpad registers the route toggle touchpad
• bin/omarchy-weather-location registers the route weather location

This filesystem-based discovery mechanism means the router automatically recognizes new commands without requiring updates to internal lookup tables or configuration files.

Longest-Prefix Route Resolution

When a user invokes the CLI, the router applies a longest-prefix matching algorithm to resolve the target binary. According to the implementation in bin/omarchy, the router walks the user-supplied arguments from left to right, attempting to match the longest possible sequence against the discovered routes.

Consider the command omarchy theme set dark:

1. The router first tests the full argument list theme set dark against all available routes.
2. Finding no exact match for three tokens, it shortens the candidate to theme set.
3. This sequence matches the omarchy-theme-set binary, establishing it as the command target.
4. The remaining argument (dark) is preserved to pass to the binary.

If the router exhausts all possible prefixes without finding a match, it falls back to alias resolution or prefix listing modes.

Alias Handling and Prefix Fallbacks

When exact route resolution fails, the router consults built-in alias tables defined within bin/omarchy itself. These aliases map common shorthand invocations to their full binary equivalents—for instance, routing omarchy screenshot to the omarchy-capture-screenshot binary.

The router also implements intelligent fallbacks for incomplete input:

• Help generation: Invoking omarchy without arguments triggers a help display aggregated from metadata embedded in each helper binary.
• Prefix listing: Partial matches like omarchy hw asus scan for all binaries matching the pattern omarchy-hw-asus-*, presenting the user with available sub-commands rather than failing with an error.

Process Replacement via Exec Dispatch

Once the router identifies the correct binary, it does not spawn a child process. Instead, it replaces its own process image entirely using the exec system call. As documented in docs/cli-router.md, this dispatch strategy provides two critical behaviors for shell integration.

First, the executed binary receives only the remaining arguments—the tokens not consumed by the longest-prefix match. In the invocation omarchy theme set dark, the binary at bin/omarchy-theme-set receives only dark as its argument vector.

Second, because the original router process is replaced rather than wrapped, the exit status of the helper binary propagates directly to the shell. This makes the router transparent to scripts that depend on accurate return codes for error handling or conditional execution flows.

Embedded Metadata and Automatic Documentation

Each helper binary can expose descriptive metadata through structured comments. The router parses lines beginning with # omarchy:summary= to extract short descriptions for each command during the discovery phase.

When generating the global help output, bin/omarchy aggregates these summaries from all discovered bin/omarchy-* files. This allows the central help text to remain synchronized with the actual command implementations without requiring manual updates to a centralized documentation file.

Summary

• The router at bin/omarchy scans "$OMARCHY_PATH/bin" for executables prefixed with omarchy- to build the command registry dynamically.
• Longest-prefix matching resolves user arguments to the most specific available binary, passing unmatched tokens as remaining arguments.
• Built-in aliases and prefix listings provide graceful fallbacks when exact matches do not exist.
• The exec system call replaces the router process, ensuring transparent exit code propagation and argument isolation.
• Metadata comments (# omarchy:summary=) enable automatic help generation without centralized configuration.

Frequently Asked Questions

How does the Omarchy CLI discover available commands?

The router dynamically builds its command manifest at runtime by scanning the bin/ directory for files matching the omarchy-* naming pattern. Each executable found automatically registers a route corresponding to its filename, requiring no additional configuration or registration steps.

What happens if I type a partial command that does not match any binary?

If the input matches no exact route or alias, the router attempts a prefix listing. For example, entering omarchy hw asus when no omarchy-hw-asus binary exists will display all available commands matching the omarchy-hw-asus-* pattern, helping you discover the correct sub-command.

Why does the Omarchy router use exec instead of spawning a subprocess?

The exec system call replaces the router process entirely with the target binary, which ensures that the helper command's exit code becomes the exit code of the original omarchy invocation. This design makes the router transparent to shell scripts that check return values for error handling or conditional logic.

How can I add a custom command to the Omarchy CLI?

Create an executable file in the bin/ directory with a name following the omarchy-<group>-<action> convention. Include a # omarchy:summary=<description> comment near the top of the file so the router can display it in help output. The new command will be available immediately without restarting the router or modifying configuration files.

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