How Omarchy Command Fallback Route Resolution Works

Omarchy's CLI driver maintains dual routing tables—COMMAND_ROUTE for explicit metadata-defined paths and COMMAND_FALLBACK_ROUTE for filename-derived paths—to ensure every binary remains callable even without declared omarchy:group or omarchy:name metadata.

Omarchy, the open-source CLI framework from the omacom/omarchy repository, implements an intelligent command routing system that guarantees binary discoverability through automatic fallback generation. When you execute omarchy <command>, the system resolves the route by checking both explicitly declared metadata and inferred filename patterns stored in bin/omarchy. This dual-table architecture ensures that every script matching bin/omarchy-* remains accessible regardless of whether it includes structured metadata comments.

Dual Routing Table Architecture

Omarchy's command-line driver constructs two distinct lookup tables during command registration. The COMMAND_ROUTE table maps binary identifiers to explicit routes derived from omarchy:group and omarchy:name metadata declarations, while the COMMAND_FALLBACK_ROUTE table stores alternative paths generated directly from the binary's filename. Both routes are inserted into the global ROUTE_TO_KEY associative array via the register_route function, enabling the resolve_route mechanism to match against either variant.

Registration and Metadata Parsing

During the registration phase, the register_command function in bin/omarchy parses the first few comment lines of each executable to extract metadata. If a script lacks omarchy:group or omarchy:name declarations, the driver automatically infers these values from the filename using string manipulation logic implemented at lines 54‑68. The system strips the omarchy- prefix and splits the remaining stem on dashes to determine the fallback group and name:

local stem="${file_binary#omarchy-}"                # strip `omarchy-` prefix

local fallback_group="$stem"
local fallback_name=""

if [[ $stem == *-* ]]; then
    fallback_group="${stem%%-*}"                    # part before first dash

    fallback_name="${stem#*-}"
    fallback_name="${fallback_name//-/ }"           # dashes → spaces

fi

[[ -z $group ]] && group="$fallback_group"
[[ $name_seen != "true" ]] && name="$fallback_name"

After parsing, the fallback route is assembled by converting dashes to spaces and stored in the fallback table:

local fallback_route="omarchy ${stem//-/ }"          # e.g. “omarchy update”

COMMAND_FALLBACK_ROUTE["$key"]="$fallback_route"
register_route "$fallback_route" "$key"

Longest Prefix Route Resolution

When a user invokes omarchy <arguments>, the resolve_route function (lines 911‑931 in bin/omarchy) attempts to match the longest possible prefix of the input against the ROUTE_TO_KEY map. The algorithm iterates from the full argument count down to one, constructing candidate routes by joining words with spaces:

for (( prefix_count = argc; prefix_count >= 1; prefix_count-- )); do
    route="omarchy $(join_words " " "${args[@]:0:prefix_count}")"
    key="${ROUTE_TO_KEY[$route]}"
    if [[ -n $key ]]; then
        RESOLVED_KEY="$key"
        RESOLVED_COUNT="$prefix_count"
        RESOLVED_ROUTE="$route"
        return 0
    fi
done

Because fallback routes are registered alongside explicit routes in the same lookup table, the resolver successfully matches commands even when users invoke them using filename-derived spellings rather than the metadata-defined paths. This longest-prefix matching ensures that omarchy backup database resolves correctly whether the explicit route is defined or only the fallback exists.

Fallback Activation Scenarios

The fallback routing system activates in three specific scenarios to ensure consistent CLI behavior:

Missing metadata. When a command script lacks omarchy:group or omarchy:name comments, the system relies entirely on the filename-derived fallback to determine the invocation path, as implemented in the registration logic.

Help output generation. Functions like fallback_group_for_key, command_route_for_group, and command_usage_for_group consult the COMMAND_FALLBACK_ROUTE table to display correct help text when the explicit route differs from the filename inference. The fallback_group_for_key function (lines 26‑31) specifically extracts the group portion from the fallback route:

fallback_group_for_key() {
    local fallback="${COMMAND_FALLBACK_ROUTE[$key]#omarchy }"
    printf '%s' "${fallback%% *}"
}

Group mismatches. If a command's explicit metadata places it in a different group than its filename suggests, command_route_for_group selects the fallback route to prevent displaying the command under an incorrect category in help listings.

Practical Route Examples

Consider a command without explicit metadata:

$ cat bin/omarchy-foo
#!/usr/bin/env bash

# omarchy:summary=Demo command with no metadata

Registration creates no explicit route but generates the fallback omarchy foo, allowing invocation via:

$ omarchy foo

# → executes bin/omarchy-foo

For a command with explicit metadata:

$ cat bin/omarchy-bar-baz
#!/usr/bin/env bash

# omarchy:group=tool

# omarchy:name=run

The system registers both routes:

• Explicit route: omarchy tool run
• Fallback route: omarchy bar baz

Both invocations work identically:

$ omarchy tool run   # uses explicit route

$ omarchy bar baz   # uses fallback route

Summary

• Omarchy maintains dual routing tables to handle both metadata-defined and filename-derived command paths.
• The register_command function in bin/omarchy parses metadata or falls back to parsing the omarchy-* filename stem for group and name inference.
• Longest prefix matching in resolve_route enables users to type partial commands that match either explicit or fallback routes stored in ROUTE_TO_KEY.
• Fallback routes ensure backward compatibility and accessibility for scripts lacking structured metadata comments.
• Helper functions like fallback_group_for_key leverage fallback data to generate accurate help documentation when explicit metadata differs from filename conventions.

Frequently Asked Questions

What happens if explicit and fallback routes conflict?

Omarchy registers both routes in the same ROUTE_TO_KEY map, making both invocations valid. The resolver accepts whichever matches first during the longest-prefix iteration, effectively allowing both the metadata-defined path and the filename-derived path to coexist without collision.

How does Omarchy determine the fallback group from a filename?

The fallback_group_for_key function extracts the group by removing the omarchy prefix from the stored fallback route and taking the first word of the remaining string. For example, a fallback route of omarchy dev deploy yields a group of dev according to the logic at lines 26‑31 in bin/omarchy.

Can a command work without any metadata comments?

Yes. If a binary lacks omarchy:group or omarchy:name metadata, the registration logic automatically constructs the route from the filename alone. A file named omarchy-backup-database becomes invocable as omarchy backup database through the fallback mechanism.

Where does the route resolution logic reside in the source?

The core resolution algorithm is implemented in the resolve_route function within bin/omarchy, specifically lines 911‑931. This function performs the longest-prefix match against the ROUTE_TO_KEY associative array that contains both explicit and fallback route entries.

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