# How to Get Help for a Specific omarchy Command: CLI Guide

> Easily find help for any omarchy command using --help or help subcommand. Get detailed usage, options, and examples for the omarchy CLI.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-26

---

**Use `omarchy <command> --help` or `omarchy help <command>` to display usage information, options, and examples for any omarchy subcommand.**

The **omarchy** CLI provides a unified help system that auto-generates documentation from command metadata. As implemented in the `basecamp/omarchy` repository, the router located in `bin/omarchy` intercepts help requests before execution, ensuring consistent usage information across all public commands.

## How the CLI Router Handles Help Requests

The entry point at `bin/omarchy` implements a **unified CLI router** that parses arguments for help flags before routing to subcommands. The router scans the argument list for `--help`, `-h`, or the literal word `help`, then prints command-specific usage derived from the command's internal metadata rather than static files.

Because the router intercepts these flags *anywhere* in the remaining arguments, you can position the help flag at the end of complex commands or immediately after the subcommand name.

### Standard Flag Syntax

Request help using the conventional POSIX flags:

```bash

# Long form

omarchy theme set --help

# Short form

omarchy theme set -h

```

Both forms trigger the same metadata-driven output, displaying:
- A short description of the command's purpose
- Supported options (including `--help` and `-h`)
- Example usage when defined in the source

### The Help Verb Syntax

Alternatively, use the literal `help` verb as either a prefix or suffix:

```bash

# Prefix form

omarchy help theme set

# Group-level help (shows all subcommands in the theme group)

omarchy theme help

```

When you invoke `omarchy theme help`, the system synthesizes group-level documentation from the `GROUP_DESCRIPTIONS` constant defined in `bin/omarchy`, listing all available subcommands within that namespace.

## JSON Output for Automation

For scripting and tooling integration, the router supports machine-readable help output. Append `--json` alongside `--help` to receive the same metadata as a JSON record:

```bash
omarchy theme set --help --json

```

This emits structured data including command descriptions, parameter types, and default values, parseable by CI/CD pipelines or IDE extensions.

## Key Implementation Files

Understanding the help system's architecture requires examining these specific source locations:

- **`bin/omarchy`** – The main CLI wrapper containing the argument parser and `GROUP_DESCRIPTIONS` array used to generate top-level and group-level help menus.
- **[`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md)** – Documentation explaining how the router intercepts `--help`/`-h`/`help` tokens and delegates to metadata generators.
- **[`docs/testing.md`](https://github.com/basecamp/omarchy/blob/main/docs/testing.md)** – Describes the test suite in `./test/cli` that validates help routing behavior and output consistency.
- **[`docs/menu.md`](https://github.com/basecamp/omarchy/blob/main/docs/menu.md)** – Details how group help synthesizes subcommand listings from the router's internal metadata registry.

## Summary

- **`omarchy <command> --help`** displays human-readable usage information for any specific command.
- **`omarchy help <command>`** provides an equivalent alias form recognized by the router.
- **Group help** via `omarchy <group> help` lists all subcommands using `GROUP_DESCRIPTIONS` from `bin/omarchy`.
- **JSON output** using `--help --json` supports automation and tooling workflows.
- The router in `bin/omarchy` automatically generates all help text from command metadata, ensuring documentation stays synchronized with code changes.

## Frequently Asked Questions

### How do I get help for omarchy theme commands?

Run `omarchy theme set --help` for a specific subcommand, or `omarchy theme help` to see all available theme operations. The router parses these requests in `bin/omarchy` and returns metadata-driven documentation for the theme group.

### Can I view omarchy help as JSON for scripting purposes?

Yes. Append `--json` to any help request: `omarchy theme set --help --json`. This outputs the command's metadata, options, and examples as a JSON object suitable for parsing in shell scripts or applications.

### What happens if I run omarchy without any arguments?

When invoked without a command, omarchy prints the top-level help menu. This output is built dynamically from the `GROUP_DESCRIPTIONS` constant in `bin/omarchy`, displaying all command groups and their descriptions.

### Where is the help text generated in the source code?

The help system is implemented in **`bin/omarchy`**, where the CLI router intercepts `--help`, `-h`, and `help` arguments before execution. The router queries each command's metadata to generate usage descriptions, option lists, and examples on demand.