How the Omarchy CLI Handles Arguments and Options

The Omarchy CLI routes commands through a two-tier resolution system that first attempts a fast filename match, then falls back to a metadata-driven routing table that parses arguments, detects help flags, and enforces required parameters.

The Omarchy command-line interface is implemented as a thin router in the single Bash script bin/omarchy. It discovers executable files prefixed with omarchy- and builds a sophisticated routing system that supports aliases, grouped commands, and automatic help generation without requiring manual configuration.

Command Discovery and Metadata Parsing

The router begins by scanning the bin/ directory to discover available commands and extract routing metadata from comment headers.

Binary Discovery via load_commands

The load_commands function walks through the bin/ directory and identifies every executable file whose name starts with omarchy-. Each discovered binary is registered via the register_command function, which establishes the foundation for both fast-path and metadata-driven routing.

# Located in bin/omarchy, lines 15-22

load_commands() {
  for cmd in bin/omarchy-*; do
    [ -x "$cmd" ] && register_command "$cmd"
  done
}

Parsing omarchy: Comments

The register_command function scans the first 80 lines of each binary for structured metadata comments formatted as # omarchy:<key>=<value>. Recognized keys include group, name, summary, args, examples, aliases, hidden, and requires-sudo. If specific keys are missing, the router falls back to filename-derived defaults.

This metadata drives the canonical routing schema (omarchy <group> <name>) and determines visibility in help listings. The implementation spans lines 50-88 in bin/omarchy.

Route Resolution Strategies

Omarchy employs a hybrid resolution strategy that prioritizes performance while maintaining flexibility for complex routing scenarios.

Fast-Path Filename Resolution

The resolve_direct_route function implements the hot path for normal execution. It joins successive argument prefixes with hyphens and checks for a matching executable file (omarchy-<prefix>). This approach bypasses metadata loading entirely, providing immediate dispatch for standard commands like omarchy theme list.

Located at lines 89-108 in bin/omarchy, this function converts space-separated arguments into hyphen-separated filenames. For example, arguments theme list become omarchy-theme-list.

Metadata-Driven Routing

When the fast-path fails, resolve_route (lines 119-131) queries the pre-built associative array ROUTE_TO_KEY for the longest-prefix match. This routing table is populated during command registration and supports:

• Canonical routes: Metadata-defined paths using group and name keys
• Filename routes: Automatic space-for-hyphen conversions (e.g., omarchy-theme-set)
• Alias resolution: Alternative names defined in the aliases metadata key

Argument and Option Handling

The CLI processes flags and validates argument requirements before dispatching to the target binary.

Detecting Help and JSON Flags

Two dedicated functions scan remaining arguments for control flags:

• remaining_has_help_flag (lines 29-36): Detects --help or -h anywhere before a -- separator
• remaining_has_json_flag (lines 40-47): Identifies --json for machine-readable output

These flags may appear in any position within the argument list, allowing commands like omarchy theme set --help or omarchy update aur --json.

Required Argument Validation

The command_requires_args function (lines 61-73) analyzes the args metadata field to determine if a command requires parameters. It strips optional bracket notation ([...]) and checks for remaining non-optional tokens.

When a command requiring arguments is invoked without them, the router automatically displays the command's help text instead of executing the binary.

Dispatch and Error Handling

The dispatch_fast_or_help and dispatch_or_help functions orchestrate the final execution phase:

1. Resolve the route using either fast-path or full-path resolution
2. If a help flag is present, invoke show_command_help or show_command_json
3. If arguments are required but missing, display usage information
4. Otherwise, exec the binary with remaining arguments

For unknown routes or missing binaries, the router exits with status 127, following standard "command not found" conventions (see error path at lines 64-71 in dispatch_or_help).

Group and Prefix Handling

When the first token matches a known group but no specific command resolves, show_group_help (invoked via group_exists at lines 86-97) lists all child commands within that group.

If no exact match exists, show_prefix_help (lines 124-138) displays commands whose usage starts with the supplied prefix, or suggest_command (lines 134-144) generates "did you mean...?" suggestions for typos.

Code Examples

# Fast-path execution (no metadata loading)

$ omarchy theme list

# Executes bin/omarchy-theme-list directly

# Metadata-driven canonical route

# File: bin/omarchy-install-gaming-xbox-cloud

# Header: # omarchy:name=xbox-cloud

$ omarchy install gaming xbox-cloud

# Resolves via ROUTE_TO_KEY metadata table

# Help flag detection anywhere in arguments

$ omarchy update aur --help

# Resolves "update", detects --help, shows omarchy-update help

# JSON-formatted help output

$ omarchy theme set --help --json

# Outputs structured JSON via show_command_json

# Automatic help for missing required arguments

$ omarchy theme set

# Requires <name> argument → displays usage instead of executing

# Group-level help listing

$ omarchy theme --help

# Lists all omarchy-theme-* commands via show_group_help

# Prefix search and suggestions

$ omarchy hw asus

# Shows commands starting with "omarchy hw asus"

$ omarchy upda

# Suggests "omarchy update" via suggest_command

Summary

• The Omarchy CLI router lives in bin/omarchy and discovers commands by scanning for omarchy-* executables.

• Fast-path resolution converts arguments to hyphenated filenames for immediate execution without metadata overhead.

• Metadata parsing extracts routing information from # omarchy: comment headers, enabling canonical routes, aliases, and grouped commands.

• Help (--help, -h) and JSON (--json) flags are detected anywhere in the remaining argument list using remaining_has_help_flag and remaining_has_json_flag.

• Commands declare required arguments via the args metadata key; invocation without these arguments triggers automatic help display.

• Unresolved routes exit with code 127, while partial matches trigger prefix listings or "did you mean" suggestions.

Frequently Asked Questions

How does Omarchy map space-separated arguments to executable files?

Omarchy uses the resolve_direct_route function to join argument prefixes with hyphens and probe for a matching file. For example, omarchy theme set checks for bin/omarchy-theme, then bin/omarchy-theme-set. This happens in bin/omarchy lines 89-108 without loading any metadata, making it the fastest execution path.

Can I place the --help flag after the command arguments?

Yes. The remaining_has_help_flag function scans all remaining arguments for --help or -h regardless of position, provided they appear before a -- separator. This allows syntax like omarchy theme list --help or omarchy update --json aur to work correctly.

What happens if I run a command without its required arguments?

The router calls command_requires_args to strip optional brackets from the metadata args field. If non-optional tokens remain and no arguments are provided, the CLI invokes show_command_help instead of executing the binary. This prevents partial command execution and displays usage instructions immediately.

How are command groups and aliases defined?

Groups and aliases are specified via metadata comments in each binary's header. The group key categorizes commands (e.g., theme), while the aliases key defines alternative invocation names. These are parsed by register_command (lines 50-88) and stored in the ROUTE_TO_KEY associative array for resolution by resolve_route.

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