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

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:

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

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

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 – Documentation explaining how the router intercepts --help/-h/help tokens and delegates to metadata generators.
• docs/testing.md – Describes the test suite in ./test/cli that validates help routing behavior and output consistency.
• 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.

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