# How to Debug Routing Surprises with `omarchy --help` > Uncover routing surprises in Omarchy by using omarchy --help. This command inspects arguments and displays group or command-specific help without running the binary. - Repository: [Omacom/omarchy](https://github.com/omacom/omarchy) - Tags: how-to-guide - Published: 2026-09-09 --- **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 --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: ```bash # 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`](https://github.com/omacom/omarchy/blob/main/docs/testing.md)**: Testing methodology for routing logic. - **[`agents/skills/command-metadata.md`](https://github.com/omacom/omarchy/blob/main/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 --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`.