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

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.

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:

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:

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

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