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

> Debug routing surprises with omarchy commands --all --json. Inspect your complete routing table, guard preludes, hidden flags, and group assignments to understand command path resolution.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: how-to-guide
- Published: 2026-09-09

---

**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`](https://github.com/omacom/omarchy/blob/main/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:

```bash

# Show the entire routing table (pretty-printed)

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

```

```bash

# Find a specific command and inspect its guard

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

```

```bash

# Detect commands that are hidden but still present

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

```

```bash

# 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"

```

```bash

# 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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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.