# How to Debug Omarchy CLI Issues: A Complete Troubleshooting Guide > Troubleshoot omarchy CLI issues with this complete guide. Learn to validate metadata permissions and inspect command configurations effectively for smoother operations. - Repository: [Omacom/omarchy](https://github.com/omacom/omarchy) - Tags: how-to-guide - Published: 2026-09-12 --- **Run `omarchy commands --check` to validate metadata and permissions, then use `--help` on specific commands to inspect their parsed configuration.** The Omarchy command-line interface is a modular system driven by a single driver script located at `bin/omarchy`. When you need to debug Omarchy CLI issues, understanding how this driver discovers sub-commands, parses metadata comments, and resolves routes is essential for quick diagnosis. The architecture delegates actual business logic to individual `omarchy-*` binaries, making most problems traceable to metadata, permissions, or routing configuration. ## Understanding the Omarchy CLI Architecture The driver script operates through three distinct phases: discovery, registration, and resolution. ### Command Discovery and Metadata Loading The `load_commands` function scans every executable file matching the pattern `omarchy-*` in the `bin/` directory. For each binary found, it calls `register_command` to parse special comment lines formatted as `# omarchy:=`. According to the source code in `bin/omarchy`, the `register_command` function extracts critical metadata keys including `group`, `name`, `summary`, `args`, `examples`, `requires-sudo`, and `hidden`. When explicit metadata is missing, the function builds a fallback route directly from the filename, ensuring commands remain accessible even with incomplete documentation. ### Route Resolution and Dispatch Once loaded, commands are stored in the associative array `ROUTE_TO_KEY`. The `resolve_route` function (and its optimized counterpart `resolve_direct_route`) performs prefix matching against user arguments to find the longest valid route match. If the remaining arguments contain `--help` or `-h`, the script triggers `dispatch_fast_or_help` or `dispatch_or_help` to render rich help pages via `show_command_help` or `show_group_help`. When resolution fails, the `suggest_command` function analyzes the input and prints a "Did you mean...?" hint, guiding users toward the closest valid command. ## Common Causes of CLI Failures Most Omarchy CLI issues stem from four specific failure modes: - **Missing or malformed metadata** - A sub-command script lacks required `# omarchy:summary=` lines or contains syntax errors in its comment blocks. - **Route collisions** - Two separate binaries declare identical `group` and `name` combinations, causing the `ROUTE_TO_KEY` lookup to fail or behave unpredictably. - **Permission errors** - A binary loses its executable bit after package updates or manual file operations, preventing the driver from discovering it. - **Argument mismatches** - The metadata declares required arguments via `# omarchy:args=` but the user provides none, or the declaration is malformed. ## Step-by-Step Debugging Workflow Follow this systematic approach to isolate and resolve CLI problems. ### Run the Internal Validator Begin every debugging session with the built-in validation command. The `show_commands_check` function (invoked via `omarchy commands --check`) verifies that every binary is executable, confirms that required metadata fields exist, and detects route collisions in the `ROUTE_TO_KEY` mapping. ```bash omarchy commands --check ``` This command outputs specific error messages for missing summaries, non-executable files, or routing conflicts, allowing you to address configuration issues before investigating further. ### Inspect Command Metadata To verify how the driver parses a specific command's metadata, request its help documentation. The `show_command_help` function displays the extracted `summary`, `args`, and `examples` exactly as the driver interprets them. ```bash omarchy update --help ``` If the help output appears incomplete or incorrect, inspect the source file directly using `head` to view the metadata comment block: ```bash head -n 30 bin/omarchy-update ``` ### Verify Binary Permissions The driver only discovers files with the executable bit set. Check permissions on problematic binaries using: ```bash ls -l $(which omarchy-) ``` If the executable flag is missing, restore it with `chmod +x bin/omarchy-` and rerun the validator. ### Trace Route Resolution When the driver reports "command not found," test the route resolution logic manually by attempting partial matches. The `resolve_route` function implements longest-prefix matching, so entering a partial command name triggers the `suggest_command` logic and reveals available alternatives. ```bash omarchy ``` ### Enable Verbose Bash Tracing For complex routing issues, temporarily enable Bash tracing by adding `set -x` at the top of `bin/omarchy`. This prints every internal step, showing exactly which functions (`load_commands`, `register_command`, `resolve_route`) execute and which binaries the driver attempts to invoke. Remove `set -x` after debugging to restore normal operation. ## Troubleshooting Common Error Patterns | Symptom | Root Cause | Solution | |---------|------------|----------| | `omarchy: command not found` after update | Binary lost executable flag | Run `chmod +x bin/omarchy-` or reinstall the package. | | "Missing metadata summary" in validation | Script lacks `# omarchy:summary=` comment | Add a descriptive summary line: `# omarchy:summary=Show battery status`. | | "Route collision" warning | Duplicate `group`/`name` declarations | Rename one command or adjust its metadata to create a unique route. | | Help shows no arguments but command requires them | Missing or malformed `# omarchy:args=` line | Add argument documentation: `# omarchy:args=[file]`. | | "No documented commands found" for a group | Binaries not executable or missing headers | Verify all scripts in the group have executable permissions and metadata headers. | ## Summary - The Omarchy CLI driver at `bin/omarchy` discovers commands via `load_commands` and parses metadata through `register_command`. - Use `omarchy commands --check` to run the `show_commands_check` validation routine and identify metadata or permission errors. - Route resolution relies on prefix matching in the `ROUTE_TO_KEY` associative array; failures trigger `suggest_command` for typo correction. - Debug specific commands with `--help` to see parsed metadata, or use `head` to inspect raw comment blocks in `bin/omarchy-*` files. - Enable `set -x` in the driver script for step-by-step execution tracing when standard diagnostics fail. ## Frequently Asked Questions ### How do I check if all omarchy commands are properly configured? Run `omarchy commands --check` to execute the internal validation suite. This command invokes `show_commands_check` to verify that every `omarchy-*` binary is executable, contains required metadata fields like `summary`, and has no route collisions in the `ROUTE_TO_KEY` mapping. The output lists specific files and errors requiring attention. ### Why does omarchy say "command not found" for a script that exists? The driver filters discovery results through `load_commands`, which only registers executable files. If a binary exists but lacks the executable bit, or if its metadata comment block is malformed (preventing `register_command` from parsing it), the command will not appear in the `ROUTE_TO_KEY` array. Verify permissions with `ls -l` and check for parsing errors by running `omarchy commands --check`. ### What causes route collisions in omarchy? Route collisions occur when two or more `omarchy-*` binaries declare identical combinations of `group` and `name` metadata keys, or when explicit aliases overlap. The `register_command` function attempts to map these to the `ROUTE_TO_KEY` array, but duplicate entries cause the validation routine to flag a collision. Resolve this by renaming one command or adjusting its `group` or `name` metadata to ensure unique routing paths. ### How can I see what routes are registered internally? Execute `omarchy commands --all` to list every discovered command, including those marked with `hidden` in their metadata. This output is generated from the `sorted_keys` function and reflects the current state of the `ROUTE_TO_KEY` array after `load_commands` has processed all binaries in the `bin/` directory.