# Understanding the Fallback Path in Omarchy CLI Command Resolution > Discover the Omarchy CLI fallback path for seamless command resolution. Learn how binaries like omarchy-new-project automatically map to omarchy new project without metadata. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: internals - Published: 2026-08-29 --- **The Omarchy CLI fallback path converts any binary named `omarchy-` into a command route formatted as `omarchy `, ensuring automatic command resolution without explicit metadata.** The Omarchy command router implements a deterministic fallback mechanism to handle CLI invocations when predefined routes are unavailable. This fallback path derives valid command routes directly from executable filenames, allowing the basecamp/omarchy toolchain to resolve commands intelligently based on naming conventions alone. The derivation logic resides in the main dispatcher script and creates a seamless bridge between binary names and CLI entry points. ## How the Fallback Path Is Constructed The fallback path generation follows a strict four-step transformation process inside `bin/omarchy`. When the router encounters an executable prefixed with `omarchy-`, it automatically constructs a derived route using bash parameter expansion. ### Binary Naming Convention The fallback mechanism activates exclusively for executables beginning with the `omarchy-` prefix. The system extracts the **stem**—the portion of the filename following this prefix—to use as the foundation for route generation. ### Stem Transformation Logic At line 256 of `bin/omarchy`, the dispatcher applies a bash substitution pattern to transform the extracted stem: ```bash fallback_route="omarchy ${stem//-/ }" ``` This substitution `${stem//-/ }` replaces every hyphen in the stem with a space character. For example, a stem of `toggle-touchpad` becomes `toggle touchpad`, resulting in the complete fallback route `omarchy toggle touchpad`. ### Route Registration Between lines 284 and 299, the script stores the derived route in the `COMMAND_FALLBACK_ROUTE` associative array and registers it with the router: ```bash COMMAND_FALLBACK_ROUTE["$key"]="$fallback_route" register_route "$fallback_route" "$key" ``` This registration ensures the fallback path is available for lookup when the router processes incoming commands. ## Runtime Resolution Using the Fallback Path When a command is invoked, the router first checks for explicit matches in `COMMAND_GROUP` and `COMMAND_NAME`. If no direct match exists, the system extracts the fallback group and name from the previously stored route. The helper function `fallback_group_for_key` (lines 425-433 in `bin/omarchy`) parses the `COMMAND_FALLBACK_ROUTE` entry to determine the appropriate command group and name for execution. This extraction allows the router to treat derived routes identically to explicitly configured ones, maintaining consistent behavior across all CLI interactions. ## Concrete Examples of Fallback Path Derivation The following examples demonstrate how binary names transform into fallback paths: ```bash # Binary: omarchy-toggle-touchpad # Fallback route becomes: omarchy toggle touchpad # Binary: omarchy-foo-bar-baz # Fallback route becomes: omarchy foo bar baz ``` In practice, invoking the binary directly triggers the fallback resolution: ```bash $ omarchy-toggle-touchpad # Internally resolves to: omarchy toggle touchpad ``` If explicit metadata defines a custom command group or name, the router uses those values instead; the fallback path serves as a safety net guaranteeing every `omarchy-*` binary remains accessible via the CLI. ## Test Coverage for Fallback Behavior The Omarchy test suite validates this fallback mechanism in `test/cli` between lines 82 and 127. These tests confirm that: - Commands lacking explicit metadata correctly infer their fallback paths - The hyphen-to-space transformation works for binaries with multiple word segments - Fallback commands appear correctly in generated documentation This coverage ensures the fallback path logic remains stable across updates to the dispatcher. ## Summary - The **fallback path** derives command routes from binary filenames using the pattern `omarchy ${stem//-/ }`. - At **line 256** of `bin/omarchy`, the dispatcher transforms hyphens to spaces using bash parameter expansion. - Derived routes are stored in `COMMAND_FALLBACK_ROUTE` and registered via `register_route` (lines 284-299). - The `fallback_group_for_key` function (lines 425-433) extracts command components from stored fallback routes during runtime. - Any binary prefixed with `omarchy-` automatically receives a functional CLI entry without manual route configuration. ## Frequently Asked Questions ### What triggers the fallback path in Omarchy CLI? The fallback path activates when the command router cannot locate an explicit route definition in `COMMAND_GROUP` or `COMMAND_NAME`. When this occurs, the system checks the `COMMAND_FALLBACK_ROUTE` array for a derived route based on the binary's filename, as implemented in the resolution logic of `bin/omarchy`. ### How does the fallback path handle binaries with multiple hyphens? The fallback path replaces every hyphen with a space using the bash substitution `${stem//-/ }`. A binary named `omarchy-network-interface-up` generates the route `omarchy network interface up`, creating a multi-word command structure that mirrors the filename's segments. ### Where is the fallback path logic implemented? The construction logic resides at line 256 of `bin/omarchy`, while the registration occurs between lines 284 and 299. Runtime extraction of fallback components happens in the `fallback_group_for_key` function at lines 425-433. Test coverage exists in `test/cli` lines 82-127. ### Can explicit metadata override the fallback path? Yes. The router prioritizes explicit metadata when available. The fallback path only serves as the default resolution strategy when no custom command group or name is defined, ensuring binaries always have a usable route while allowing developers to specify precise routing when needed.