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

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

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

# 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: Shell-level tests confirming --help detection across various command contexts
• 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	Router algorithm specification and help interception rules
test/cli	Automated CLI behavior verification
test/shell.d/hermes-cli-test.sh	Shell integration tests for help flag handling
manual/14-omarchy-cli.md	User-facing CLI documentation

Summary

• Router-based interception: 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.

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