How to Check for Command Alias and Route Collisions in the Omarchy CLI

Run omarchy commands --json to inspect metadata mappings and execute ./test/cli to validate that no duplicate aliases exist across the command registry.

The Omarchy CLI from Basecamp relies on a strict routing layer that maps user input to command binaries using both primary IDs and declared aliases. Understanding how to check for command alias and route collisions in the Omarchy CLI ensures that new commands do not shadow existing ones or create ambiguous routing paths. This guide explains the metadata structure in bin/omarchy, the collision detection algorithm in shell/plugins/menu/MenuModel.js, and the validation commands available in the codebase.

Where Omarchy Stores Command Aliases

The GROUP_DESCRIPTIONS Metadata Table

The central dispatcher at bin/omarchy defines a GROUP_DESCRIPTIONS table that serves as the source of truth for all registered commands. Each entry in this metadata structure includes an aliases array populated from the --aliases flag used during command registration. This array stores free-form strings that map alternative input tokens to the same binary, such as mapping "omarchy screenshot" to the omarchy-capture-screenshot command.

Command JSON Structure

When you invoke omarchy commands --json, the CLI serializes the metadata into JSON format. Each command object exposes its identifier, binary path, and associated aliases. Inspecting this output reveals how the routing layer interprets user input before executing the underlying script.

How the Routing Layer Resolves Aliases

Exact ID Matching with Alias Fallback

The routing algorithm implemented in shell/plugins/menu/MenuModel.js prioritizes exact command IDs over aliases. When the CLI receives a token, it first queries the map for a direct identifier match. If no exact ID exists, the system performs a linear scan of every command's aliases array to locate a matching string.

Token Normalization Rules

Before comparison, the router normalizes input tokens to lower-case and substitutes underscores with hyphens. This ensures that inputs like power_menu and power-menu resolve to the same target. The normalization logic guarantees consistent matching regardless of how the user formats their command.

Detecting Route Collisions Automatically

The Collision Detection Algorithm

At startup, the routing code constructs two lookup maps: one mapping id → command and another mapping alias → id. If the builder encounters the same alias string assigned to multiple commands, it records a conflict and aborts initialization with a descriptive error. This preventive check ensures that ambiguous routes cannot exist in the runtime environment.

Built-in Test Validation

The test/cli suite contains automated checks that verify every declared alias appears in the JSON metadata and that no duplicates exist across the registry. Running this suite guarantees that any new alias introduced by a developer is vetted for collisions before deployment.

Manual Validation Techniques

Inspect current aliases using jq:

omarchy commands --json | jq '.commands[] | {binary, aliases}'

Verify specific alias resolution:

omarchy routes "power-menu"

Attempting to register a duplicate alias produces an immediate error:

omarchy register --name mycmd --aliases power-menu

# error: alias "power-menu" already mapped to command "system"

Run the full collision test suite:

./test/cli

Summary

• Command metadata resides in bin/omarchy within the GROUP_DESCRIPTIONS table, where each entry includes an aliases array populated during registration.
• Routing logic in shell/plugins/menu/MenuModel.js checks exact IDs first, then scans aliases after normalizing tokens to lower-case with hyphen substitution.
• Collision detection occurs at startup by building id→command and alias→id maps; duplicate aliases trigger a fatal error that prevents CLI launch.
• Validation can be performed manually via omarchy commands --json or automatically via the ./test/cli test suite.

Frequently Asked Questions

How do I list all active aliases in Omarchy?

Execute omarchy commands --json and pipe the output to jq '.commands[].aliases' to extract every registered alias. This displays the complete mapping of shortcut strings to their primary command binaries.

What happens if two commands share the same alias?

The startup routine detects the collision while building the alias mapping table and aborts with an error message indicating which alias conflicts and which commands share it. This prevents the CLI from launching until the duplicate is resolved in the metadata.

Can I override a built-in alias with a custom command?

No, the collision prevention logic in shell/plugins/menu/MenuModel.js treats all aliases as unique across the entire namespace. You must first remove or rename the existing alias from the built-in command metadata in bin/omarchy before assigning it to a custom binary.

Where is the alias collision test suite located?

The collision tests reside in the test/cli directory. Executing this suite validates that the JSON output from omarchy commands contains no duplicate entries in any aliases array and that the routing table builds without conflicts.

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