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

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:

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

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

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

# 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 | Formal documentation of routing mechanics and flag handling | | docs/file-layout.md | Directory structure and naming conventions | | 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.

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