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

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:

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:

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:

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	Documentation of the CLI routing system, describing groups, routes, and the --check flag
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.

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