# How the Omarchy CLI Router Maps Commands: File-Based Dispatch Explained > Discover how the Omarchy CLI router maps commands using file-based dispatch and longest-prefix matching to execute scripts in your bin directory. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: internals - Published: 2026-08-27 --- **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--` 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--`. 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 `, 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`](https://github.com/basecamp/omarchy/blob/main/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--*` 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 ```bash # 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--` 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--`, 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--` 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.