# How omarchy Handles `--help` Flag Anywhere in Arguments

> Discover how omarchy handles the --help flag anywhere in arguments. Learn how omarchy's CLI router displays help for resolved routes instantly.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: internals
- Published: 2026-09-06

---

**Omarchy's CLI router intercepts `--help` or `-h` at any position in the argument list and displays help for the resolved route instead of executing the command.**

Omarchy uses a sophisticated routing system to dispatch commands to the correct handler. A key usability feature is how it handles help requests—users can append `--help` anywhere in their command without worrying about position. This behavior is implemented in the CLI router and rigorously tested across the codebase.

## CLI Router Architecture and Help Detection

The routing logic lives in [`docs/cli-router.md`](https://github.com/omacom/omarchy/blob/main/docs/cli-router.md). When omarchy receives a command, the **router** parses arguments into two distinct parts:

- **The route**: The sequence of words resolving to a group or sub-command
- **The leftovers**: Remaining arguments passed to the final binary

During parsing, the router **scans leftovers for `--help` or `-h` anywhere in the sequence**. If found, execution short-circuits and help text prints for the resolved route.

According to the router documentation, the system "intercepts `--help`/`-h` *anywhere* in the leftover arguments" before invoking the target command. This ensures users always receive documentation instead of unintended execution.

## Exception: The `--` Separator

The router respects explicit argument boundaries. When users include `--` in their command, only arguments before this separator are examined for help flags.

```bash

# --help is intercepted by the router

omarchy update aur --help

# --help is forwarded to the underlying binary

omarchy foo run -- --help

```

Arguments after `--` are treated as literal values passed through to the final executable without router interpretation.

## Practical Command Examples

```bash

# Help for an entire group

omarchy theme --help

# Help for a specific sub-command

omarchy capture screenshot --help

# Help works mid-command (not just trailing)

omarchy update --help aur

# JSON-formatted help output

omarchy theme --help --json

```

The `--json` flag combines with `--help` to emit structured help output for programmatic consumption.

## Test Coverage and Verification

Omarchy's behavior is enforced through multiple test suites:

- **`test/cli` (lines 664-682)**: Verifies trailing `--help` never executes the target command and always renders help
- **[`test/shell.d/hermes-cli-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/hermes-cli-test.sh)**: Shell-level tests confirming `--help` detection across various command contexts
- **[`test/shell.d/default-agent-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/default-agent-test.sh)**: Additional coverage for edge cases in argument parsing

These tests ensure the "help-anywhere" guarantee holds across omarchy's entire command surface.

## Key Implementation Files

| Path | Purpose |
|------|---------|
| [`docs/cli-router.md`](https://github.com/omacom/omarchy/blob/main/docs/cli-router.md) | Router algorithm specification and help interception rules |
| `test/cli` | Automated CLI behavior verification |
| [`test/shell.d/hermes-cli-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/hermes-cli-test.sh) | Shell integration tests for help flag handling |
| [`manual/14-omarchy-cli.md`](https://github.com/omacom/omarchy/blob/main/manual/14-omarchy-cli.md) | User-facing CLI documentation |

## Summary

- **Router-based interception**: [`docs/cli-router.md`](https://github.com/omacom/omarchy/blob/main/docs/cli-router.md) defines how the `--help` flag anywhere in arguments triggers help output
- **Position-independent**: `--help` or `-h` works at any point in the command, not just at the end
- **`--` separator support**: Arguments after `--` bypass help detection and pass through literally
- **JSON output**: Combine `--help --json` for machine-readable documentation
- **Comprehensive testing**: Multiple test files enforce correct behavior across scenarios

## Frequently Asked Questions

### What happens if I put `--help` in the middle of arguments?

Omarchy's router detects `--help` regardless of position. The command `omarchy update --help aur` displays help for `omarchy update` without attempting to process `aur` as a sub-command.

### Can I pass `--help` to the actual command being run?

Yes. Use the `--` separator to bypass router interception. The command `omarchy foo run -- --help` forwards `--help` directly to the binary invoked by `omarchy foo run`.

### Does `-h` work the same as `--help`?

Yes. The router treats both `-h` and `--help` identically for help detection purposes.

### Is help output available in machine-readable format?

Yes. Append `--json` alongside `--help` to receive JSON-structured help documentation suitable for tooling integration.