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

> Prevent command alias and route collisions in Omarchy CLI by inspecting metadata with `omarchy commands --json` and running `./test/cli` to validate.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-21

---

**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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`:

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

```

Verify specific alias resolution:

```bash
omarchy routes "power-menu"

```

Attempting to register a duplicate alias produces an immediate error:

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

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

```

Run the full collision test suite:

```bash
./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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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.