# How Omarchy Handles `--help` and `-h` Arguments in Its CLI

> Discover how Omarchy handles --help and -h arguments. Learn about its early flag detection, usage info printing, and zero-code exit for efficient CLI interaction.

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

---

**Omarchy** processes help flags through a centralized router in `bin/omarchy` that detects `--help` or `-h` early, prints usage information from the `GROUP_DESCRIPTIONS` array to STDOUT, and exits with code `0` before any sub-command execution.

The **Omarchy CLI** follows a hierarchical command structure where help requests are intercepted at the entry point. In the `basecamp/omarchy` repository, the top-level executable `bin/omarchy` acts as a command router that parses arguments and dispatches to group-specific scripts, ensuring consistent **Omarchy CLI help arguments** behavior across the entire toolchain.

## Centralized Help Routing in `bin/omarchy`

The primary logic resides in the **`bin/omarchy`** router script. This executable implements early argument inspection to intercept help requests before routing to sub-commands.

### Argument Detection via Case Statement

Early in the script execution, a `case` statement evaluates each argument. When the parser encounters either `--help` or `-h`, it immediately branches to a dedicated help-handling block, bypassing all command routing logic and preventing unintended command execution.

### Dynamic Help Generation from `GROUP_DESCRIPTIONS`

The help block constructs a usage synopsis by reading the **`GROUP_DESCRIPTIONS`** array defined within `bin/omarchy`. This array maps command groups—such as `capture-`, `theme-`, and `toggle-`—to their descriptions. The script assembles these into a formatted table displaying available command groups and their purposes, as documented in [`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md).

### STDOUT Output and Clean Exit

The constructed help text prints to **STDOUT** and includes:

- A generic usage line: `omarchy <group> [options] …`
- A listing of all command groups with brief descriptions
- Instructions to run `omarchy <group> --help` for detailed group-specific help

After output, the script exits with status code `0`, following standard Unix conventions for successful informational display.

## Distributed Help Handling in Sub-Commands

Each **group-specific script** (e.g., `bin/omarchy-theme-list`, `bin/omarchy-capture-screen`) implements identical help flag detection. These scripts check for `--help` or `-h` early in their execution, print their own usage information (often derived from internal `USAGE` variables or script comment blocks), and exit cleanly.

This design ensures that invoking `omarchy theme --help` provides specific theme command documentation, while `omarchy --help` shows the global overview derived from the central router.

## Practical Usage Examples

Display top-level help:

```bash
omarchy --help

# or

omarchy -h

```

Expected output structure:

```

Usage: omarchy <group> [options] …
Groups:
  capture-   Screenshots, recordings, and related utilities
  theme-     Theme management commands
  toggle-    Toggle features on/off
Run "omarchy <group> --help" for details about a specific group.

```

Display group-specific help:

```bash
omarchy theme --help

```

Expected output:

```

Theme commands:
  omarchy-theme-list          List available themes
  omarchy-theme-set <name>    Apply a theme
  omarchy-theme-refresh       Refresh the current theme

```

## Summary

- **Early Interception**: The `bin/omarchy` router detects `--help` and `-h` via case statement logic before command dispatch.
- **Centralized Documentation**: Help content derives from the `GROUP_DESCRIPTIONS` array, ensuring consistency across command groups.
- **Hierarchical Support**: Both the top-level router and individual `bin/omarchy-<group>` scripts implement parallel help handling mechanisms.
- **Clean Termination**: All help invocations exit with status code `0` and output to STDOUT, following POSIX conventions.

## Frequently Asked Questions

### Where is the help logic implemented in Omarchy's source code?

The primary help handling resides in **`bin/omarchy`**, the central CLI router. This script contains the argument parsing logic and the `GROUP_DESCRIPTIONS` array that defines the help content for command groups, as detailed in [`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md). Individual sub-commands in `bin/omarchy-<group>` files implement their own help output for specific functionality.

### Can I use `-h` interchangeably with `--help` in Omarchy?

Yes. The parser in `bin/omarchy` explicitly checks for both the short flag `-h` and the long flag `--help`, treating them identically. Both trigger the same help generation block and exit with status code `0`.

### How does Omarchy handle help requests for specific command groups?

When you invoke `omarchy <group> --help`, the router passes control to the specific group script (e.g., `bin/omarchy-theme-list`). That script independently checks for help flags and displays its own usage information, typically listing available sub-commands and their parameters.

### What exit code does Omarchy return when displaying help?

Omarchy exits with status code **`0`** (success) after printing help information. This behavior applies to both top-level help (`omarchy --help`) and group-specific help requests, ensuring compatibility with standard Unix conventions where informational output indicates successful execution.