# How the Omarchy CLI Handles Arguments and Options

> Learn how the Omarchy CLI handles arguments and options using its two-tier resolution system for efficient command routing and parameter enforcement. Discover its fast filename match and metadata-driven approach.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: how-to-guide
- Published: 2026-09-12

---

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

```bash

# 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

```bash

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