# How to Check for Omarchy Command Route Collisions: Validation and Detection Guide

> Discover how to check for omarchy command route collisions using `omarchy commands --check`. Detect conflicting command paths and ensure routing integrity with this essential guide.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: how-to-guide
- Published: 2026-09-04

---

**Use `omarchy commands --check` to detect route collisions, which validates that no two binaries claim the same command path and returns a non-zero exit status if conflicts exist in the internal `ROUTE_COLLISIONS` array.**

The `omacom/omarchy` framework builds its CLI routing table by scanning executables in `bin/omarchy-*`, mapping each command to its owning binary. When two binaries attempt to register the same route (e.g., `omarchy theme`), the collision is captured during initialization and can be surfaced through the built-in validation system.

## How Route Collisions Occur in Omarchy

In `bin/omarchy`, the **`register_route`** function (lines 55-62) processes each discovered command and maintains the routing infrastructure. This function records the textual route (e.g., `omarchy update`) together with the binary that owns it in the `ROUTE_TO_KEY` mapping.

If a route is already mapped to a different binary, the conflict is stored in the **`ROUTE_COLLISIONS`** array 🛑. This detection happens automatically during the command loading phase, ensuring that duplicate registrations are caught before the CLI becomes operational.

## Detecting Collisions with the `--check` Flag

The **`show_commands_check`** function (lines 96-108) implements the validation logic triggered by `omarchy commands --check` 🔎. This routine iterates over `ROUTE_COLLISIONS` and prints every collision to stderr.

Beyond route conflicts, this check validates:
- Missing command summaries
- Malformed flag definitions
- Missing binary files

The command returns a non-zero exit status if any problems are found, making it ideal for pre-deployment validation in CI/CD pipelines.

## Step-by-Step Collision Detection

The collision-detection mechanism operates in two distinct phases:

1. **During command loading** – Each command's route is registered via `register_route`; duplicate routes are captured in `ROUTE_COLLISIONS`.
2. **On-demand validation** – Running `omarchy commands --check` reports the stored collisions alongside other metadata errors.

## Practical Examples

Run the basic check to see any route collisions:

```bash
omarchy commands --check

```

Example output when a collision exists:

```

Route collision: omarchy theme -> omarchy-theme conflicts with omarchy-theme-set
Command metadata check failed (1 issues)

```

Use the check in scripts to enforce a clean routing table before deployment:

```bash
if ! omarchy commands --check >/dev/null; then
  echo "Route collisions detected – fix them before release"
  exit 1
fi

```

## Inspecting Raw Route Data via JSON

If you need to inspect the raw list of routes and identify duplicates manually, dump the JSON representation and process it with standard Unix tools:

```bash
omarchy commands --json | jq -r '.commands[].route' | sort | uniq -c | awk '$1 > 1 {print $2}'

```

This approach validates the integrity of `ROUTE_TO_KEY` independently of the built-in collision detector.

## Key Source Files

| File | Purpose |
|------|---------|
| `bin/omarchy` | Core router that loads commands, builds `ROUTE_TO_KEY`, detects collisions in `register_route`, and implements `omarchy commands --check` in `show_commands_check` |
| [`docs/cli-router.md`](https://github.com/omacom/omarchy/blob/main/docs/cli-router.md) | Documentation of the CLI routing system, describing groups, routes, and the `--check` flag |
| [`AGENTS.md`](https://github.com/omacom/omarchy/blob/main/AGENTS.md) | Overview of the authoritative list of command groups (`GROUP_DESCRIPTIONS`) used by the router |

## Summary

- **Route registration** happens in `bin/omarchy` via the `register_route` function, which populates `ROUTE_COLLISIONS` when duplicates are detected.
- **Validation** is performed by `show_commands_check` when you run `omarchy commands --check`.
- **Exit codes** are non-zero when collisions or other metadata issues exist, enabling automated enforcement in deployment scripts.
- **Alternative inspection** is available through the `--json` flag for custom validation logic.

## Frequently Asked Questions

### What causes an omarchy command route collision?

A collision occurs when two separate binaries under `bin/omarchy-*` attempt to register the same command path. For example, if both `omarchy-theme` and `omarchy-theme-set` try to claim the route `omarchy theme`, the second registration triggers the `register_route` function to log the conflict in `ROUTE_COLLISIONS`.

### How do I fix a detected route collision?

Rename the conflicting binary or modify its internal route registration to use a unique path. After making changes, run `omarchy commands --check` again to verify that `ROUTE_COLLISIONS` is empty and the exit status is zero.

### Can I check for collisions in automated scripts?

Yes. The `omarchy commands --check` command returns a non-zero exit status when collisions or other metadata errors are found. You can use this in CI/CD pipelines to prevent deployments with conflicting routes, as shown in the scripting example above.

### Does the collision check validate other metadata issues?

Yes. According to the source code in `bin/omarchy` (lines 96-108), `show_commands_check` simultaneously validates missing command summaries, malformed flags, and missing binaries alongside route collisions, providing a comprehensive metadata health report.