How to Get Help with Omarchy CLI Commands: A Complete Guide to the Router and Metadata System

Omarchy's CLI provides built-in help through a lightweight router that reads metadata from script headers, allowing you to run omarchy --help for global commands or append --help to any group or command for specific usage details.

Omarchy is an open-source automation framework maintained in the omacom/omarchy repository that uses a unique file-based routing system to handle CLI commands. Understanding how to access help documentation is essential for navigating its spaced-command syntax and discovering available functionality. This guide covers the router implementation in bin/omarchy and the metadata system that powers the help output.

Understanding the Omarchy CLI Router

The core routing logic resides in bin/omarchy, which scans executable scripts matching the pattern bin/omarchy-* to map spaced commands (such as theme set) to individual files (such as bin/omarchy-theme-set). When you request help, the router intercepts --help or -h flags anywhere in the argument list before command execution occurs, ensuring you never accidentally run a command while seeking documentation.

This router implements longest-prefix matching to resolve commands, falling back to metadata parsing when filename routes don't align perfectly with user input. The detailed routing behavior is documented in docs/cli-router.md.

Accessing Global and Contextual Help

Viewing the Top-Level Command List

Running omarchy without arguments—or explicitly with omarchy --help—prints the global command list. The router generates this output from the hand-curated GROUP_DESCRIPTIONS table defined within bin/omarchy itself, giving you an overview of available command groups like capture, theme, and commands.

Getting Help for Specific Groups and Commands

For targeted assistance, append --help to any group or full command path:

• omarchy <group> --help shows all commands within that group
• omarchy <group> <command> --help displays usage, arguments, and examples for that specific operation

If a command requires arguments but you provide none, the router automatically displays the generated help rather than executing with missing parameters.

The Metadata-Driven Help System

Omarchy's help generation relies on command metadata embedded in the first 80 lines of each script file. These comment-based headers use structured keys defined in agents/skills/command-metadata.md:

• # omarchy:summary=Description of what the command does

• # omarchy:args=Required and optional parameters

• # omarchy:examples=Usage examples

When you request --help, the router reads this metadata to synthesize the help output dynamically. For example, bin/omarchy-theme-set contains # omarchy:summary=Apply an Omarchy theme, which appears in help listings.

Introspecting Commands with omarchy commands

Beyond standard help flags, Omarchy provides the omarchy commands introspection utility for programmatic discovery:

• omarchy commands lists every non-hidden command with its summary
• omarchy commands --json outputs the complete JSON record including routes, groups, arguments, and examples
• omarchy commands --all --markdown generates a Markdown table including hidden commands

These options enable integration with external tooling and documentation generators.

Practical Examples for Accessing Help

# Show the top-level command list and available groups

omarchy --help

# Display all commands in the capture group

omarchy capture --help

# View detailed usage for the theme set command

omarchy theme set --help

# Export complete command metadata as JSON for scripting

omarchy commands --json

# Generate a Markdown table of all commands including hidden ones

omarchy commands --all --markdown

Each invocation reads the metadata declared in the corresponding script file (e.g., bin/omarchy-theme-set).

Summary

• The Omarchy CLI router in bin/omarchy maps spaced commands to bin/omarchy-* scripts using filename parsing and longest-prefix matching.

• Help metadata is declared in script headers within the first 80 lines using keys like # omarchy:summary= and # omarchy:args=, as specified in agents/skills/command-metadata.md.

• Run omarchy --help for the global command list derived from the GROUP_DESCRIPTIONS table, or append --help to any group or command for specific documentation.

• Use omarchy commands to list available operations, with --json or --markdown flags for machine-readable output.

• The router automatically shows help when arguments are missing or when --help appears anywhere in the command line.

Frequently Asked Questions

How do I see all available Omarchy commands?

Run omarchy commands to display a human-readable list of every non-hidden command with its summary. For programmatic use, append --json to get the full metadata record including routes and arguments defined in each script's metadata headers.

Where is the Omarchy CLI help documentation defined?

Help content lives in two places: the GROUP_DESCRIPTIONS table inside bin/omarchy provides the global command list, while individual command documentation resides in metadata headers within each bin/omarchy-* script file. The metadata format specification is located at agents/skills/command-metadata.md.

Can I get help output in JSON format for scripting?

Yes. While --help produces human-readable text, the omarchy commands --json command outputs comprehensive JSON containing route definitions, argument specifications, examples, and aliases for all commands. This is ideal for automation and integration with external tools.

What happens if I run an Omarchy command without required arguments?

The router detects missing required arguments and automatically displays the command's help documentation instead of executing. This safety mechanism ensures you see usage instructions and examples before attempting to run the command again with proper parameters.

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