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

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 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:

# 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

# 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

# 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

# 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

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

# 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	Architectural documentation explaining the spaced-command to flat-binary mapping
agents/skills/command-metadata.md	Authoring guidelines for the # omarchy:<key>=<value> metadata format

| 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) 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, 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 file in the Omarchy repository explains the routing architecture, while manual/14-omarchy-cli.md covers user-facing CLI patterns. For metadata authoring specifics, see agents/skills/command-metadata.md.

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