How to Debug Routing Surprises with `omarchy <route> --help`

Appending --help or -h to any Omarchy route triggers the dispatcher in bin/omarchy to resolve the target binary, inspect remaining arguments via remaining_has_help_flag, and render either group-level or command-specific help without executing the underlying binary.

The Omarchy command-center (located in bin/omarchy within the omacom/omarchy repository) translates textual routes such as omarchy theme list into binary executables. When you append --help to a command, the system must distinguish between executing the binary and displaying its documentation. Understanding how the dispatcher resolves routes and detects help flags is essential to debug routing surprises such as ignored flags, unexpected group listings, or "unknown command" errors.

How the Dispatcher Resolves Routes

The entry point script bin/omarchy implements a two-phase resolution strategy to map your input to an executable binary. According to the source code, the process differentiates between direct binary matches and fallback route construction.

Phase 1: Direct Route Resolution

The function resolve_direct_route (lines 99‑110) attempts to find an exact binary matching the longest possible prefix of your arguments. For example, when you run omarchy theme list, it searches for an executable named omarchy-theme-list. If found, the dispatcher considers this a direct match and proceeds to check for help flags in the remaining arguments.

Phase 2: Fallback Route Resolution

If no direct binary exists, resolve_route (lines 191‑210) progressively shortens the argument list to find a known route. This handles cases where you invoke a parent group without specifying a full sub-command path. Once resolved, dispatch_or_help (lines 223‑232) again checks for help flags before execution.

The Help Flag Detection Mechanism

Once a binary or route is identified, the dispatcher determines whether to execute it or display help documentation based on specific parsing logic.

Scanning Remaining Arguments

The remaining_has_help_flag function (lines 29‑36) scans arguments that remain after the matched prefix for --help or -h, stopping if it encounters a -- separator. This ensures flags appearing after -- (which are passed through to the binary itself) do not accidentally trigger the help display.

Help Display Routing

Inside dispatch_fast_or_help (lines 55‑77), the logic branches based on whether the resolved prefix represents a group or a specific command:

• Group help: When the prefix resolves to a single-word group (e.g., theme), the system calls show_group_help (lines 800‑822) to list available child commands.
• Command help: For specific binaries (e.g., theme list), it invokes show_command_help to display detailed usage, or show_command_json for machine-readable output.

Debugging Common Routing Issues

When omarchy <route> --help behaves unexpectedly, the root cause typically lies in binary resolution, flag detection, or metadata conflicts.

Symptom: --help is ignored and the binary executes Likely, remaining_has_help_flag returned false because the flag appeared after a -- separator or was misspelled. Verify the exact syntax and ensure --help precedes any -- argument separator.

Symptom: Group list appears instead of specific command help The dispatcher resolved only the group (e.g., omarchy theme) because the binary for the sub-command (omarchy-theme-list) was missing or not executable. Run omarchy commands --check to identify missing binaries or route collisions.

Symptom: "Unknown command" with no valid suggestions show_prefix_help (lines 824‑839) failed to find commands starting with your input. The system falls back to suggest_command within dispatch_or_help (lines 64‑71) to recommend the closest match. Ensure your binaries have the executable bit set using chmod +x bin/omarchy-theme-list.

Symptom: Route collision errors in validation The show_commands_check function (lines 698‑733) reveals when two binaries register identical routes via their omarchy: metadata headers, causing undefined resolution behavior. Examine the collision output and rename conflicting commands or adjust their metadata.

Essential Diagnostic Commands

Use these commands to inspect and validate the routing system:

# List all commands including hidden ones

omarchy commands --all

# Validate metadata and detect route collisions

omarchy commands --check

# Output help as JSON for programmatic inspection

omarchy theme list --help --json

Key Source Files

Understanding these files helps trace execution flow:

• bin/omarchy: Core dispatcher containing dispatch_fast_or_help, resolve_direct_route, and remaining_has_help_flag.
• bin/omarchy-*: Individual command binaries (e.g., omarchy-theme, omarchy-theme-list) containing metadata headers that define groups and routes.
• docs/testing.md: Testing methodology for routing logic.
• agents/skills/command-metadata.md: Guidelines for proper omarchy: metadata structure to prevent routing conflicts.

Summary

• The dispatcher in bin/omarchy uses resolve_direct_route and resolve_route to map inputs to binaries through direct matching or progressive fallback.
• remaining_has_help_flag detects --help in arguments only before the -- separator.
• Group help displays via show_group_help while specific command help uses show_command_help or JSON variants.
• Use omarchy commands --check to detect missing binaries, permission issues, and route collisions that cause surprising behavior.

Frequently Asked Questions

Why does omarchy theme list --help run the command instead of showing help?

This occurs when remaining_has_help_flag returns false, typically because --help appears after a -- argument separator or the binary omarchy-theme-list does not exist causing a fallback to an executable parent script. Verify the flag position and run omarchy commands --check to confirm the specific binary exists and is executable.

How can I identify which binary the dispatcher selected for my route?

While the dispatcher resolves binaries internally, you can infer selection logic by running omarchy commands --all to view registered routes. If omarchy theme --help displays a group list rather than command output, the system resolved to the group binary (omarchy-theme) rather than a specific sub-command binary.

What triggers the "Route collision" warning in omarchy commands --check?

This warning appears when two separate binaries in bin/ contain identical omarchy: metadata route declarations. The show_commands_check function (lines 698‑733) cross-references all binaries to detect these conflicts, which can cause the dispatcher to resolve to an unexpected executable during routing.

Why does omarchy <unknown> --help sometimes show a prefix list instead of an error?

When resolve_route cannot find an exact match, show_prefix_help (lines 824‑839) attempts to list any commands starting with the given prefix. If matches exist, it displays them as suggestions; otherwise, dispatch_or_help prints an "unknown command" message along with guidance from suggest_command.

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