# How to Get Help with Omarchy CLI Commands: A Complete Guide to the Router and Metadata System > Master Omarchy CLI commands with our guide. Learn to use the router and metadata system to access help for global commands, groups, and specific scripts easily. - Repository: [Omacom/omarchy](https://github.com/omacom/omarchy) - Tags: how-to-guide - Published: 2026-09-12 --- **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`](https://github.com/omacom/omarchy/blob/main/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 --help` shows all commands within that group - `omarchy --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`](https://github.com/omacom/omarchy/blob/main/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 ```bash # 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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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.