Understanding the Fallback Path in Omarchy CLI Command Resolution

The Omarchy CLI fallback path converts any binary named omarchy-<stem> into a command route formatted as omarchy <stem-with-spaces>, 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:

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:

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:

# 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:

$ 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.

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