# How Omarchy Maps Commands to Executables: A Deep Dive into the CLI Router

> Discover how Omarchy maps CLI commands to executables using a filename convention and a Bash router script. Learn about binary discovery, metadata parsing, and invocation dispatch.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: deep-dive
- Published: 2026-09-02

---

**Omarchy maps CLI commands to executables through a convention-based filename pattern and a Bash router script that discovers binaries, parses inline metadata, and dispatches invocations.**

The `omacom/omarchy` project implements a lightweight, self-contained command routing system entirely within the single script `bin/omarchy`. This router eliminates the need for external dependency management or complex build steps, instead relying on filename conventions and structured comments to build a complete command-line interface.

## Command Discovery via Filename Convention

The router begins by scanning its own directory for files matching the pattern `omarchy-*`. This discovery loop runs early in the script at lines 150–166:

```bash

# Simplified representation of the discovery mechanism

for candidate in "$OMARCHY_BIN_DIR"/omarchy-*; do
    # Skip the router itself and non-executable files

    [[ "$candidate" == "$OMARCHY_BIN_DIR/omarchy" ]] && continue
    [[ -x "$candidate" ]] || continue
    
    register_command "$candidate"
done

```

Every executable file found becomes a candidate command. The filename itself encodes critical routing information.

## Group and Name Derivation from Filenames

Omarchy parses the filename `omarchy-<group>-<verb>` to extract:

- **Group**: The functional category (e.g., `toggle`, `update`, `config`)
- **Command name**: The specific action (e.g., `touchpad`, `system`)

This parsing occurs in `register_command` (lines 68–78), where the router populates `COMMAND_GROUP[key]` and `COMMAND_NAME[key]`:

| Filename | Group | Command | Full Route |
|----------|-------|---------|------------|
| `omarchy-toggle-touchpad` | `toggle` | `touchpad` | `toggle touchpad` |
| `omarchy-update-system` | `update` | `system` | `update system` |
| `omarchy-config-show` | `config` | `show` | `config show` |

The router stores the absolute path to each binary in `COMMAND_BINARY[key]` for later execution.

## Metadata Extraction from Comment Annotations

Each command binary can declare structured metadata through specially formatted comments in its first *METADATA_SCAN_LIMIT* lines. The `register_command` function (source at lines 10–23 for array declarations) extracts:

- `# omarchy:summary=…` — Short description for help output

- `# omarchy:usage=…` — Usage string template

- `# omarchy:args=…` — Argument descriptions

- `# omarchy:examples=…` — Example invocations

- `# omarchy:requires-sudo=true` — Automatic privilege escalation

- `# omarchy:hidden=true` — Exclude from help listings

- `# omarchy:alias=…` — Alternative route names

These values populate associative arrays including `COMMAND_SUMMARY`, `COMMAND_USAGE`, `COMMAND_REQUIRES_SUDO`, and `COMMAND_ALIAS`.

## Route Registration and Dispatch

With metadata extracted, the router builds dispatchable routes. The `register_route` function (lines 50–66) creates mappings in `ROUTE_TO_KEY`:

```bash

# Routes are constructed as "group name" or "group" alone

route="$group $name"      # e.g., "toggle touchpad"

route_group_only="$group"  # e.g., "toggle"

ROUTE_TO_KEY["$route"]=$key
ROUTE_TO_KEY["$route_group_only"]=$key  # If no name component

```

Aliases from `# omarchy:alias=` receive identical treatment.

When a user executes `omarchy toggle touchpad`, the router:

1. Attempts **longest-match lookup** in `ROUTE_TO_KEY`
2. Checks `COMMAND_REQUIRES_SUDO` for the matched key
3. Prefixes with `omarchy-sudo` if required
4. Invokes `COMMAND_BINARY[key]` with remaining arguments
5. Preserves special flags (`--help`, `-h`, `--json`) through the call chain

The execution block implementing this dispatch appears around lines 350–380 of `bin/omarchy`.

## Group Listings and Help Output

`GROUP_DESCRIPTIONS` (declared starting at line 27 with entries through line 96) provides human-readable titles for each group:

```bash
GROUP_DESCRIPTIONS[toggle]="Toggle Omarchy features"
GROUP_DESCRIPTIONS[update]="System update operations"
GROUP_DESCRIPTIONS[config]="Configuration management"

```

When a user types a group without a subcommand—e.g., `omarchy toggle`—the router filters commands by `COMMAND_GROUP` and prints formatted summaries using `COMMAND_SUMMARY`.

## Practical Examples

```bash

# List all commands in the toggle group

omarchy toggle

# Output:

#   touchpad    Toggle the touchpad on/off

#   screensaver Toggle the screensaver state

#   wifi        Toggle WiFi radio

# Execute a specific command

omarchy toggle touchpad

# Internally executes: bin/omarchy-toggle-touchpad

# Command requiring elevated privileges

omarchy update system

# Router detects requires-sudo and executes:

#   omarchy-sudo bin/omarchy-update-system

```

## Key Files in the Routing System

| File | Purpose |
|------|---------|
| `bin/omarchy` | Central router implementing discovery, metadata parsing, route registration, and dispatch |
| `bin/omarchy-<group>-<verb>` | Individual command implementations with optional `# omarchy:*` metadata |

| [`docs/cli-router.md`](https://github.com/omacom/omarchy/blob/main/docs/cli-router.md) | Formal documentation of routing mechanics and flag handling |
| [`docs/file-layout.md`](https://github.com/omacom/omarchy/blob/main/docs/file-layout.md) | Directory structure and naming conventions |
| [`AGENTS.md`](https://github.com/omacom/omarchy/blob/main/AGENTS.md) | Authoritative `GROUP_DESCRIPTIONS` reference |

## Summary

- **Discovery**: The router scans `bin/omarchy-*` to find candidate commands
- **Naming**: Filenames follow `omarchy-<group>-<verb>` to encode routing information
- **Metadata**: Inline comments declare descriptions, usage, aliases, and sudo requirements
- **Storage**: Bash associative arrays (`COMMAND_*`, `ROUTE_TO_KEY`, `GROUP_DESCRIPTIONS`) hold runtime state
- **Dispatch**: Longest-match route lookup resolves user input to executable binaries with automatic privilege escalation

## Frequently Asked Questions

### How does Omarchy handle naming conflicts between commands?

The router rejects duplicate routes during registration. If two binaries would generate identical `ROUTE_TO_KEY` entries, `register_route` detects the collision and exits with an error. Aliases must also be unique across the entire command set.

### Can custom commands be added without modifying the router?

Yes. Any executable file matching `bin/omarchy-<group>-<verb>` with proper metadata comments is automatically discovered and registered on the next invocation. No changes to `bin/omarchy` are required.

### What happens if a command metadata comment is malformed?

Malformed metadata lines are silently skipped during the scan. The command remains functional but may display generic help text or lack descriptive information in group listings. The `requires-sudo` and `hidden` flags default to false when unspecified.