How the Omarchy CLI Router Maps Commands: File-Based Dispatch Explained

The Omarchy CLI router uses a longest-prefix matching algorithm to map command-line arguments to executable scripts in the bin/ directory, progressively truncating arguments until it finds a matching omarchy-<group>-<verb> binary.

The basecamp/omarchy repository implements its command-line interface through a lightweight Bash dispatcher located at bin/omarchy. This router eliminates complex argument parsing by treating the filesystem itself as the command registry, mapping user input directly to executable scripts that follow strict naming conventions.

File-Based Verb Discovery

The router discovers available commands by scanning the bin/ directory for executable files matching the pattern omarchy-*. Each filename encodes its logical group and verb using the convention omarchy-<group>-<verb>. For example, bin/omarchy-theme-set implements the theme set command, while bin/omarchy-hw-asus handles the hw asus subcommand. According to the source code in bin/omarchy, the router builds an internal index of these files at runtime to determine valid command paths.

Longest-Prefix Matching Algorithm

When a user invokes omarchy <arguments>, the router applies a deterministic resolution strategy:

1. Full argument match: The router first attempts to locate a binary matching all provided arguments (e.g., theme set dark).
2. Progressive truncation: If no exact match exists, it drops the trailing argument and retries (e.g., theme set).
3. Prefix resolution: This continues until the router finds the longest valid prefix that corresponds to an executable file.
4. Parameter passing: Remaining arguments are forwarded as positional parameters to the target script.

This algorithm, documented in docs/cli-router.md, enables nested subcommands without requiring explicit routing tables for every permutation.

Group Descriptions and Metadata

Inside bin/omarchy, the router constructs an associative array called GROUP_DESCRIPTIONS that maps command groups to human-readable help text. The router populates this structure by scanning bin/omarchy-<group>-* files and extracting the first comment line from each script. This metadata drives the help output when users invoke omarchy without arguments or request assistance for a specific group.

Command Aliases and Fallback Behavior

The router supports command aliases through explicit mappings within the dispatch logic. For instance, omarchy screenshot resolves to the capture group, routing to bin/omarchy-capture-* binaries rather than requiring a literal screenshot script. When the router cannot resolve a valid prefix, or when invoked with zero arguments, it falls back to displaying contextual help derived from GROUP_DESCRIPTIONS, listing available groups and their descriptions.

Process Dispatch and Execution

Once the router identifies the target binary, it uses exec to replace its own process with the selected script. This implementation detail ensures that:

• The exit status of the underlying command propagates directly to the calling shell.
• No intermediary process remains in the process table.
• Signal handling and standard I/O streams pass through unmodified to the target executable.

JSON Introspection Mode

The router supports machine-readable introspection through the --json flag. When invoked as omarchy --json, bin/omarchy outputs a structured representation of all discovered routes, including group names, available verbs, and extracted descriptions. This feature enables programmatic discovery of the CLI surface area for integration with shell completions or documentation generators.

Practical Usage Examples

# Display top-level help using GROUP_DESCRIPTIONS

omarchy

# Resolve to bin/omarchy-theme-set with "dark" as argument

omarchy theme set dark

# Resolve to bin/omarchy-hw-asus

omarchy hw asus

# Use an alias: "screenshot" maps to the "capture" group

omarchy screenshot now

# Output all routes as JSON

omarchy --json

Summary

• The Omarchy CLI router relies on executable filenames in bin/ following the omarchy-<group>-<verb> pattern to define valid commands.
• Resolution uses a longest-prefix algorithm that progressively drops trailing arguments until finding a matching binary in bin/omarchy.
• Metadata for help text is extracted dynamically from the first comment line of each command script and stored in the GROUP_DESCRIPTIONS array within bin/omarchy.
• Aliases such as screenshot mapping to capture are handled through explicit fallback logic in the router.
• The router uses exec to dispatch to target scripts, ensuring clean process replacement and exit code propagation.
• The --json flag enables introspection of the entire command tree for tooling integration.

Frequently Asked Questions

How does the Omarchy CLI router handle unknown commands?

When the router cannot match the provided arguments to any bin/omarchy-* file using longest-prefix matching, it displays a help message listing available commands within the matched group (if any) or the full command index. This behavior is implemented in the main dispatch loop of bin/omarchy and leverages the GROUP_DESCRIPTIONS associative array to provide contextual suggestions.

What naming convention must command scripts follow?

All routable commands must be executable files located in the bin/ directory and prefixed with omarchy-. The filename structure follows omarchy-<group>-<verb>, where group represents the command category and verb represents the specific action. For example, bin/omarchy-theme-set correctly maps to omarchy theme set, while bin/omarchy-hw-asus maps to omarchy hw asus.

Can I add custom commands to the Omarchy CLI?

Yes. Create a new executable file in bin/ following the omarchy-<group>-<verb> naming convention, ensure it has execute permissions, and include a descriptive comment on the first line. The router will automatically discover the new command on the next invocation and include it in GROUP_DESCRIPTIONS for help output. No changes to the router script itself are required.

How do I view all available commands programmatically?

Invoke omarchy --json to output a machine-readable description of every route the router knows. This JSON structure includes all groups, verbs, and descriptions extracted from the source files, making it suitable for generating shell completions, documentation, or integration with other tooling.

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