How to Get Help with Omarchy Commands: Complete CLI Help Guide

To get help with Omarchy commands, use omarchy --help for top-level commands, omarchy <group> <command> --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

# 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

# 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	Technical documentation covering routing algorithms and dispatch behavior
agents/skills/command-metadata.md	Complete specification of comment-based metadata syntax
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 <group> <command> --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 <command> --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.

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