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

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.

# 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 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.

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:

# 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 and 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.

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