# How Omarchy Command Fallback Route Resolution Works

> Discover how Omarchy command fallback route resolution ensures every binary is callable using dual routing tables for explicit and filename-derived paths. Learn more.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: internals
- Published: 2026-09-11

---

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

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
$ 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:

```bash
$ omarchy foo

# → executes bin/omarchy-foo

```

For a command with explicit metadata:

```bash
$ 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:

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