# How to Get Help with Omarchy Commands: Complete CLI Help Guide > Master Omarchy commands with this CLI help guide. Learn to get help for top-level commands, specific usage, and list all available commands easily. - Repository: [Omacom/omarchy](https://github.com/omacom/omarchy) - Tags: how-to-guide - Published: 2026-08-31 --- **To get help with Omarchy commands, use `omarchy --help` for top-level commands, `omarchy --help` for specific usage, or `omarchy commands` to list all available commands.** Omarchy's command-line interface uses a lightweight **router** system that maps spaced commands to executable scripts in the `bin/` directory. Understanding how this help system works—built around metadata-driven documentation and automatic `--help` interception—lets you quickly discover commands, inspect arguments, and troubleshoot routing issues without leaving your terminal. ## How the Omarchy CLI Router Handles Help Requests The help system in Omarchy is powered by two core components: the router in `bin/omarchy` and **metadata declarations** embedded in command scripts. ### Router-Based Command Discovery In `bin/omarchy`, the router scans all `bin/omarchy-*` files and derives **groups** and **commands** from filenames. A file named `omarchy-theme-set` becomes the command `omarchy theme set`—group `theme`, command `set`. The router implements **longest-prefix matching** with fallback to metadata when direct filename routes don't match. This design means help content stays synchronized with the actual executable scripts, since documentation lives inside the files themselves. ### Metadata-Driven Help Generation Each command script declares help content in comment headers within its first 80 lines. The router parses keys like: - `# omarchy:summary=` — Brief description shown in listings - `# omarchy:args=` — Argument specifications - `# omarchy:examples=` — Usage examples When you request `--help`, the router extracts this metadata and synthesizes formatted output without executing the command. --- ## Command Examples for Accessing Omarchy Help ### Basic Help Invocations ```bash # Top-level command list with all groups omarchy --help # Help for an entire command group omarchy capture --help # Help for a specific command omarchy theme set --help ``` The router intercepts `--help` (or `-h`) **anywhere** in the argument list, ensuring safe inspection before execution. ### Listing and Introspecting All Commands ```bash # Human-readable list of all non-hidden commands omarchy commands # Complete JSON record for programmatic use omarchy commands --json # Include hidden commands in Markdown table format omarchy commands --all --markdown # JSON help for a specific command omarchy theme set --help --json ``` The `omarchy commands` subcommand enumerates every discovered command with its summary, while `--json` outputs the full metadata record including route, group, arguments, and examples—ideal for shell scripts and IDE integrations. ### Automatic Help on Missing Arguments If a command requires arguments and none are provided, the router **automatically displays generated help** instead of failing. This behavior is implemented in the argument-parsing logic of `bin/omarchy`, ensuring users always see relevant documentation rather than cryptic errors. --- ## Key Source Files Behind Omarchy's Help System | File | Purpose | |------|---------| | `bin/omarchy` | Core router implementing command mapping, `--help` interception, and metadata parsing | | `bin/omarchy-theme-set` | Example command demonstrating metadata declarations (`summary`, `args`, `examples`) | | [`docs/cli-router.md`](https://github.com/omacom/omarchy/blob/main/docs/cli-router.md) | Technical documentation covering routing algorithms and dispatch behavior | | [`agents/skills/command-metadata.md`](https://github.com/omacom/omarchy/blob/main/agents/skills/command-metadata.md) | Complete specification of comment-based metadata syntax | | [`manual/14-omarchy-cli.md`](https://github.com/omacom/omarchy/blob/main/manual/14-omarchy-cli.md) | User-facing manual summarizing common groups and workflow patterns | The `GROUP_DESCRIPTIONS` table inside `bin/omarchy` provides the hand-curated content shown in top-level `--help`, while individual scripts maintain their own detailed documentation. --- ## Summary - **`omarchy --help`** displays the curated top-level group listing from `bin/omarchy` - **`omarchy --help`** shows command-specific usage, arguments, and examples extracted from script metadata - **`omarchy commands`** lists all non-hidden commands; add `--json` for machine-readable full records - The router in `bin/omarchy` parses `# omarchy:*` comment headers (first 80 lines) to generate all help content - Missing required arguments trigger automatic help display rather than execution errors --- ## Frequently Asked Questions ### What happens if I run `omarchy` with no arguments? Running `omarchy` without arguments prints the top-level command list, identical to `omarchy --help`. This list is generated from the `GROUP_DESCRIPTIONS` table defined directly in `bin/omarchy`. ### Where is the help text actually stored in Omarchy? Help text lives inside each command script as **comment-based metadata**. For example, `bin/omarchy-theme-set` contains lines like `# omarchy:summary=Apply an Omarchy theme`. The router reads these declarations (limited to the first 80 lines) when generating help output—no separate documentation files to maintain. ### How can I get help output in a format my script can parse? Use **`omarchy commands --json`** for a complete JSON dump of all commands, or **`omarchy --help --json`** for single-command metadata. These outputs include structured fields for route, group, arguments, examples, and aliases. ### Why does Omarchy show help instead of running when I forget arguments? The router explicitly checks for required arguments before execution. When arguments are missing, it automatically falls back to synthesized help rather than failing with an error. This behavior is hardcoded into the dispatch logic in `bin/omarchy` as a usability safeguard.