# How to Discover Omarchy Commands: A Complete Guide to CLI Exploration

> Easily discover Omarchy commands with the `omarchy commands` CLI tool. Explore all options using flags like --all, --json, or --markdown for comprehensive CLI exploration in this complete guide.

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

---

**Run `omarchy commands` to list all available commands, with optional `--all`, `--json`, or `--markdown` flags for hidden, machine-readable, or documentation-formatted output.**

Omarchy's command discovery system centers on a single driver script that introspects its own `bin/` directory to reveal every available operation. Whether you're new to the framework or building automation scripts, understanding how Omarchy discovers and exposes its commands helps you navigate the CLI efficiently. This guide walks through the discovery mechanism, output formats, and underlying source code that powers command exploration in the [omacom/omarchy](https://github.com/omacom/omarchy) repository.

## How Omarchy Command Discovery Works

The discovery process happens automatically when you run any variation of the `omarchy commands` subcommand. The driver script at `bin/omarchy` implements a lightweight metadata-driven system that scans, parses, and registers every executable binary in the same directory.

### The Driver Script Architecture

In `bin/omarchy`, the `load_commands` function iterates over every `omarchy-*` file in the `bin/` folder and calls `register_command` for each one. This happens at lines 17-21 of the driver:

```bash

# From bin/omarchy#L17-L21 — loads all omarchy-* binaries

load_commands() {
    for cmd in "$OMARCHY_ROOT/bin"/omarchy-*; do
        register_command "$cmd"
    done
}

```

Each binary is expected to contain special metadata comments at the top. The `register_command` function scans approximately the first 80 comment lines and extracts key-value pairs matching the `# omarchy:<key>=<value>` pattern (lines 89-112).

### Metadata-Driven Route Construction

From the parsed metadata, Omarchy constructs two types of routes:

1. **Primary route** — Formed as `omarchy <group> <name>` from the `group` and `name` metadata keys
2. **Fallback route** — Derived directly from the filename (e.g., `omarchy theme list` for `omarchy-theme-list`)

These routes are stored in associative arrays (`COMMAND_ROUTE`, `ROUTE_TO_KEY`) for fast lookup during execution.

The metadata extraction supports these keys:
- `group` — Command category (e.g., `theme`, `app`, `system`)
- `name` — Specific action within the group
- `summary` — Short description for command listings
- `args` — Expected arguments syntax
- `aliases` — Alternative invocation names
- `requires-sudo` — Privilege requirements flag
- `hidden` — Visibility control for `commands` output

## Listing Omarchy Commands: The CLI Interface

The `show_commands` function (lines 84-102) formats the collected routes into a human-readable table when you run the discovery command.

### Basic Command Discovery

```bash

# List all visible commands (default)

omarchy commands

```

This displays commands where `# omarchy:hidden` is not set to `true`, organized by group with summaries and argument hints.

### Including Hidden Commands

```bash

# Show all commands including hidden internals

omarchy commands --all

```

The `--all` flag bypasses the visibility filter at lines 48-51, exposing commands intended for advanced users or framework development.

### Machine-Readable JSON Output

```bash

# Export command metadata as JSON for scripting

omarchy commands --json

```

This pipes the internal table through a `jq` filter (lines 90-98), producing structured output with fields like `route`, `summary`, `args`, `group`, and `hidden` status. Ideal for shell scripts, IDE integrations, or automation pipelines.

### Documentation-Ready Markdown

```bash

# Generate a Markdown table for documentation

omarchy commands --markdown

```

The `--markdown` flag (lines 126-134) emits a formatted table suitable for copying into README files or GitHub documentation. This is how the Omarchy project keeps its CLI reference synchronized with the actual binary implementations.

## Inspecting Specific Command Groups

For targeted help, append `--help` to any group prefix:

```bash

# Show available theme subcommands

omarchy theme --help

```

This triggers the router's help display for that group without requiring full command discovery.

## Key Source Files for Deep Understanding

| File | Purpose |
|------|---------|
| `bin/omarchy` | Central driver implementing `load_commands`, `register_command`, and `show_commands` |
| [`docs/cli-router.md`](https://github.com/omacom/omarchy/blob/main/docs/cli-router.md) | Architectural documentation explaining the spaced-command to flat-binary mapping |
| [`agents/skills/command-metadata.md`](https://github.com/omacom/omarchy/blob/main/agents/skills/command-metadata.md) | Authoring guidelines for the `# omarchy:<key>=<value>` metadata format |

| [`manual/14-omarchy-cli.md`](https://github.com/omacom/omarchy/blob/main/manual/14-omarchy-cli.md) | End-user documentation covering CLI patterns and discovery workflows |

The CLI router documentation (lines 3-34 of [`docs/cli-router.md`](https://github.com/omacom/omarchy/blob/main/docs/cli-router.md)) explains the design rationale: Omarchy exposes a hierarchical spaced-command interface (`omarchy theme install`) while internally routing to flat executable names (`omarchy-theme-install`). This dual mapping simplifies both user experience and binary organization.

## Summary

- **`omarchy commands`** is the primary discovery tool, scanning `bin/omarchy-*` files and parsing `# omarchy:` metadata comments to build its registry

- **Three output flags** control visibility and format: `--all` includes hidden commands, `--json` enables scripting, `--markdown` generates documentation
- **Metadata-driven routing** in `bin/omarchy` extracts `group`, `name`, `summary`, `aliases`, and other properties from the first ~80 lines of each binary
- **Source files** `bin/omarchy`, [`docs/cli-router.md`](https://github.com/omacom/omarchy/blob/main/docs/cli-router.md), and supporting documentation provide complete transparency into the discovery mechanism

## Frequently Asked Questions

### How does Omarchy know which commands exist?

The driver script `bin/omarchy` uses `load_commands` to walk the `bin/` directory at startup, calling `register_command` on each `omarchy-*` file. It parses `# omarchy:<key>=<value>` metadata comments to build route mappings stored in associative arrays.

### Can I list Omarchy commands programmatically?

Yes. Use `omarchy commands --json` to receive structured JSON output containing routes, summaries, argument specifications, and visibility flags. This integrates cleanly with shell scripts, automation tools, and IDE command palettes.

### What makes a command "hidden" in Omarchy output?

A command is hidden when its metadata includes `# omarchy:hidden=true`. Hidden commands remain fully functional but are excluded from standard `omarchy commands` listings. Use `--all` to reveal them, or check the source binaries directly.

### Where is the command discovery logic documented?

The [`docs/cli-router.md`](https://github.com/omacom/omarchy/blob/main/docs/cli-router.md) file in the Omarchy repository explains the routing architecture, while [`manual/14-omarchy-cli.md`](https://github.com/omacom/omarchy/blob/main/manual/14-omarchy-cli.md) covers user-facing CLI patterns. For metadata authoring specifics, see [`agents/skills/command-metadata.md`](https://github.com/omacom/omarchy/blob/main/agents/skills/command-metadata.md).