# How the Omarchy CLI Handles `--help` and `-h` Flags: Complete Technical Guide

> Discover how the Omarchy CLI handles --help and -h flags with its remaining_has_help_flag function. Learn how it intercepts help requests before they reach other binaries.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: deep-dive
- Published: 2026-09-02

---

**The Omarchy CLI implements a dedicated `remaining_has_help_flag` helper function in `bin/omarchy` that scans leftover arguments for `--help` or `-h`, stopping at `--` to ensure help requests are intercepted before reaching invoked binaries.**

The Omarchy command-line interface provides a robust routing system that guarantees users always get help documentation when requested, even in complex command invocations. This article examines how Omarchy's CLI handles help flags, from the low-level flag detection in `bin/omarchy` to the dispatch logic documented in the project's router specification.

## The `remaining_has_help_flag` Helper Function

At the core of Omarchy's help flag handling is a purpose-built bash function defined in `bin/omarchy` (lines 28–36). This function iterates through remaining arguments after route matching, searching for `--help` or `-h` while respecting argument boundaries.

```bash

# bin/omarchy – lines 28-36

remaining_has_help_flag() {
  local token=""
  for token in "$@"; do
    [[ $token == "--" ]] && break
    [[ $token == "--help" || $token == "-h" ]] && return 0
  done
  return 1
}

```

The function operates with two critical behaviors:

- **Early termination at `--`** — The literal `--` token marks where arguments should be forwarded to the underlying binary, not interpreted by the router. When encountered, scanning stops immediately and the flag is not considered a router-level help request.
- **Return code signaling** — Returns `0` (success) if a help flag is found, `1` otherwise, enabling straightforward conditional logic in the dispatch routine.

## How the Router Dispatch Logic Intercepts Help Flags

The CLI router documented in [`docs/cli-router.md`](https://github.com/omacom/omarchy/blob/main/docs/cli-router.md) uses `remaining_has_help_flag` to determine execution flow. After matching a command route, the router checks leftover arguments for help flags before invoking the target binary.

This design handles several invocation patterns correctly:

1. **Standard help request** — `omarchy capture --help` shows the capture group's help
2. **Nested command help** — `omarchy capture screenshot --help` shows the screenshot command's help
3. **Flag after subcommand arguments** — `omarchy update aur --help` still resolves as a help request
4. **Forwarded help** — `omarchy foo run -- --help` passes the flag through to the underlying binary

When the helper returns success, the router loads command metadata and renders formatted help output. The `--json` flag can be combined with `--help` to switch output format.

## Automatic Help Fallback for Missing Required Arguments

The Omarchy CLI router implements a defensive usability pattern: commands with required arguments automatically display help when invoked without them.

This automatic fallback ensures users see usage information rather than encountering unexpected execution failures. The behavior is consistent across all commands and groups, as documented in [`manual/14-omarchy-cli.md`](https://github.com/omacom/omarchy/blob/main/manual/14-omarchy-cli.md).

## Practical Examples of Help Flag Handling

Every Omarchy command and command group accepts `--help` or `-h` flags. The following examples demonstrate the router's behavior across different scenarios:

```bash

# Show help for an entire command group

omarchy capture --help

# Show help for a specific command within a group

omarchy capture screenshot --help

# Help flag positioned after subcommand arguments — still intercepted

omarchy update aur --help

# Forward help flag to underlying binary using "--" separator

omarchy foo run -- --help

```

## Help Output Formats

The Omarchy CLI supports multiple help output formats controlled by additional flags:

- **Human-readable** (default) — Plain text with formatting suitable for terminal display
- **JSON** — Machine-parseable output when `--json` is passed alongside `--help`

This dual-format approach supports both interactive terminal usage and programmatic tooling integration.

## Summary

- The **`remaining_has_help_flag`** function in `bin/omarchy` (lines 28–36) provides reliable help flag detection with `--` boundary respect
- The **router dispatch logic** checks leftover arguments after route matching, enabling help flags anywhere in the command line
- **Automatic help fallback** occurs when required arguments are missing
- **`--help`** and **`-h`** are accepted by all commands and groups per [`docs/cli-router.md`](https://github.com/omacom/omarchy/blob/main/docs/cli-router.md) and [`manual/14-omarchy-cli.md`](https://github.com/omacom/omarchy/blob/main/manual/14-omarchy-cli.md)
- **Output formatting** switches between human-readable and JSON via the `--json` flag

## Frequently Asked Questions

### Does Omarchy support the short `-h` form for help?

Yes. The `remaining_has_help_flag` function explicitly checks for both `--help` and `-h`. Either form triggers the help output regardless of position in the leftover arguments. This is documented in the CLI router specification and the manual page.

### What happens if I use `--` before the help flag?

The flag is forwarded to the underlying binary instead of being intercepted. The `remaining_has_help_flag` function breaks its scanning loop immediately upon encountering `--`, treating everything after as arguments for the invoked command. Use this syntax when you want the target program's help, not Omarchy's.

### Can I get JSON-formatted help output?

Yes. Pass `--json` together with `--help` or `-h`. The router detects both flags and renders the command metadata as JSON rather than human-readable text. This enables integration with external tools and automation scripts that parse Omarchy's command structure programmatically.