How to Debug Routing Surprises with omarchy commands --all --json

Use omarchy commands --all --json to inspect the complete routing table, revealing exactly which guard preludes, hidden flags, and group assignments determine how the CLI resolves command paths.

When the Omarchy CLI behaves unexpectedly—showing missing commands, executing wrong scripts, or hiding tools from menus—the issue usually lies in the routing logic. The omarchy commands --all --json flag exposes the dispatcher's internal decision-making process as machine-readable JSON, providing a single source of truth for command resolution according to the omacom/omarchy source code.

Understanding the Omarchy Routing Architecture

The routing process builds the command table once at startup by scanning executable files and parsing metadata annotations.

Command Discovery in bin/

The dispatcher in bin/omarchy scans the bin/ directory for executable files whose names begin with the omarchy- prefix. Each file becomes a command entry in the routing table. The router extracts metadata from the file’s shebang and inline comments, specifically looking for # omarchy:hidden= and # omarchy:guard= directives. Any stray duplicate binaries or stale files appear as separate entries in this table, making them visible to the JSON output before they cause runtime confusion.

Guard Preconditions and Hidden Flags

Two critical metadata annotations control command visibility and execution:

• Guard preludes: Defined via # omarchy:guard=, these scripts execute first to determine if the real command should run. For example, # omarchy:guard=omarchy-cmd-present checks prerequisites before allowing execution.

• Hidden flags: Marked with # omarchy:hidden=true, these commands are omitted from the user-facing menu but remain accessible in the routing table.

Groups are assigned based on the prefix following omarchy- (such as toggle or theme), with group descriptions defined in bin/omarchy under GROUP_DESCRIPTIONS.

Debugging Routing Surprises with JSON Output

The JSON payload provides the definitive view of how the router interprets each command, exposing why a specific path was selected or blocked.

The JSON Schema Explained

Each object in the JSON array represents one command with the following structure:

Key	Description
name	Full command name (e.g., omarchy-toggle-touchpad)
path	Absolute path to the script file
group	Command category (e.g., toggle)
hidden	Boolean indicating menu visibility
guard	Name of the guard prelude that ran
metadata	Arbitrary key/value pairs from script comments

When a command runs the wrong script or disappears from the menu, inspect these fields to see exactly which path the router selected and why.

Step-by-Step Debugging Workflow

Follow this systematic approach to resolve routing anomalies:

1. Confirm existence: Run omarchy commands --all --json to verify the command exists and check its path field.
2. Inspect metadata: Use omarchy commands <name> --json to narrow the view and verify guard and hidden values.
3. Check guard logic: If a guard is present, examine its source in guard-prelude-test.sh or run omarchy cmd-present <name> to see if the router considers the command available.
4. Detect duplicates: Run omarchy commands --all | grep <name> to spot naming collisions or duplicate definitions.
5. Validate annotations: Review the source script’s header comments to ensure # omarchy:hidden= and # omarchy:guard= annotations are correct.

Practical Code Examples for Routing Debugging

Use these commands to extract specific routing information from the JSON output:

# Show the entire routing table (pretty-printed)

omarchy commands --all --json | jq '.' > /tmp/omarchy-routing.json

# Find a specific command and inspect its guard

omarchy commands toggle-touchpad --json | jq '{name, guard, hidden}'

# Detect commands that are hidden but still present

omarchy commands --all --json |
  jq -r '.[] | select(.hidden == true) | .name'

# Verify that a guard is behaving as expected

# (Assuming the guard is `omarchy-cmd-present`)

omarchy cmd-present toggle-touchpad && echo "guard passes" || echo "guard blocks"

# Cross-check that the path resolved by the router matches the file on disk

omarchy commands toggle-touchpad --json |
  jq -r '.path' |
  xargs -I{} test -x {} && echo "executable exists"

Key Source Files Behind the Router

Understanding these files demystifies how the routing table is constructed:

• bin/omarchy: The main dispatcher script responsible for building the routing table and defining GROUP_DESCRIPTIONS.
• agents/skills/command-metadata.md: Documentation of the command-metadata annotations (hidden, guard, etc.) that the router parses.
• test/shell.d/guard-prelude-test.sh: Test suite demonstrating how guard preludes affect routing; essential for reproducing routing surprises.
• default/omarchy/omarchy-menu.jsonc: Menu schema defining which commands appear in the UI—note that commands hidden here are still present in the routing table.
• test/shell.d/bin-style-test.sh: Verifies that all bin/ commands use proper helpers; useful for diagnosing hidden-command bugs.

Summary

• omarchy commands --all --json outputs the definitive routing table showing how every command resolves to a concrete script.
• Routing decisions depend on file discovery in bin/, guard preludes that can short-circuit execution, and hidden flags that suppress menu visibility.
• Guard preludes silently prevent commands from running; the JSON guard field reveals which prelude executed.
• Hidden commands remain in the JSON output with "hidden": true, distinguishing configuration issues from missing files.
• Debugging workflow involves checking the JSON schema fields, verifying file paths, and testing guards with omarchy cmd-present.

Frequently Asked Questions

Why is my command missing from the menu but appearing in the JSON output?

The command has # omarchy:hidden=true in its header comments or is filtered by the menu schema in default/omarchy/omarchy-menu.jsonc. Because the JSON routing table includes all discovered executables regardless of visibility flags, you will see the entry with "hidden": true. Remove the hidden annotation or update the menu configuration to restore visibility.

How do guard preludes affect command routing?

Guard preludes act as pre-execution checks defined via # omarchy:guard=. When a guard like omarchy-cmd-present fails, the router short-circuits the command before the main script runs, often making the command appear unavailable. The JSON output shows the guard name in the guard field, allowing you to identify which prerequisite check is blocking execution.

Can I debug routing problems without using the --json flag?

While omarchy commands --all provides a textual list, the --json format is essential for debugging because it exposes the guard, hidden, and metadata fields that explain why a command routes a specific way. Use jq to parse the JSON and filter for specific conditions that plain text cannot reveal.

What causes duplicate routing entries for the same command?

Duplicate entries occur when multiple executable files in the bin/ directory share the same omarchy- prefix name, or when stale symlinks point to old script versions. Since the dispatcher scans the entire bin/ directory at startup, every unique file path creates a distinct routing table entry. Remove or rename the duplicate binaries to resolve the collision.

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