How to Debug Omarchy CLI Issues: A Complete Troubleshooting Guide

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:<key>=<value>.

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.

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.

omarchy update --help

If the help output appears incomplete or incorrect, inspect the source file directly using head to view the metadata comment block:

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:

ls -l $(which omarchy-<name>)

If the executable flag is missing, restore it with chmod +x bin/omarchy-<name> 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.

omarchy <partial-name>

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-<name> 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.

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