How Omarchy Manages System and Runtime Binaries: A Metadata‑Driven Command System

Omarchy's command‑center uses a single dispatcher script that discovers, registers, and routes to executable Bash scripts through declarative metadata annotations.

The bin/omarchy file serves as the central dispatcher for the Omarchy cli environment. Rather than hardcoding command lists, it dynamically scans the bin/ directory and builds routing tables from embedded metadata comments in each binary script.

The Dispatcher Architecture

At startup, the main dispatcher performs three core operations:

1. Directory scanning — The load_commands function (lines 17‑20) iterates through bin/omarchy-* files
2. Metadata parsing — register_command (lines 104‑112) extracts structured data from comment headers
3. Route resolution — Runtime lookup via resolve_route and resolve_direct_route maps human‑readable commands to concrete binaries

This design allows Omarchy to manage system and runtime binaries through a unified interface while maintaining clear privilege separation.

Binary Metadata Format

Each executable script begins with structured comments following the pattern # omarchy:<key>=<value>:

#!/usr/bin/env bash

# omarchy:group=system

# omarchy:summary=Apply system configuration changes

# omarchy:requires-sudo=true

# omarchy:hidden=true

# omarchy:examples=omarchy apply system --install-user alice

set -euo pipefail

# ... command implementation

Supported metadata keys:

• group — Command category for help organization
• summary — Brief description shown in listings
• name — Override the default route name
• requires-sudo — Elevated privileges required (true/false)
• hidden — Exclude from default help output (true/false)
• examples — Usage examples for documentation

How System Binaries Work

System‑level commands in Omarchy are ordinary scripts marked with requires-sudo=true. The bin/omarchy-apply-system binary demonstrates this pattern:

#!/usr/bin/env bash

# omarchy:group=system

# omarchy:summary=Apply system configuration

# omarchy:requires-sudo=true

# omarchy:hidden=true

When a user runs:

omarchy apply system --install-user alice --first-install

The dispatcher executes this resolution chain:

1. Parses apply system into route components
2. Locates bin/omarchy-apply-system via the COMMAND_ROUTE table
3. Reads requires-sudo metadata (line 5 in the source file)
4. Verifies root privileges (lines 61‑64 in bin/omarchy)
5. Executes exec "$binary_path" "${remaining[@]}"

System binaries typically include hidden=true to reduce noise in casual help listings, since they require administrative context.

How Runtime Binaries Work

Runtime binaries comprise the majority of Omarchy commands. They omit privilege flags and remain visible in standard help output.

Creating a new runtime command requires only a properly named file with metadata headers:

#!/usr/bin/env bash

# omarchy:group=network

# omarchy:summary=Show current network status

# omarchy:examples=omarchy network status

# omarchy:name=status

set -euo pipefail
echo "Network status: $(ip route get 1.1.1.1 2>/dev/null || echo 'disconnected')"

Save this as bin/omarchy-network-status. The dispatcher automatically registers it under omarchy network status on next invocation — no registry edits or recompilation needed.

Routing Table Internals

The dispatcher maintains three lookup structures during execution:

# From bin/omarchy implementation

declare -gA COMMAND_ROUTE      # Maps route keys to binary paths

declare -gA ROUTE_TO_KEY       # Maps full routes to registration keys  

declare -gA BINARY_TO_KEY      # Maps binary paths to keys

These tables enable both direct binary invocation and hierarchical route resolution. The resolve_route function handles multi‑word commands like omarchy network status by progressive key matching through the route components.

Querying the Command Registry

Omarchy exposes its internal registry through the commands subcommand:

# List visible runtime commands

omarchy commands

# Include hidden system binaries

omarchy commands --all

# Machine‑readable output for scripting

omarchy commands --all --json

The --json format emits the parsed metadata for each registered binary, including privilege requirements and visibility status.

Summary

• Omarchy manages system and runtime binaries through a unified metadata‑driven dispatcher in bin/omarchy
• Privilege separation is declarative: requires-sudo=true marks system binaries without code changes
• The load_commands and register_command functions (lines 17‑20 and 104‑112) enable automatic discovery of new binaries
• Route resolution combines hierarchical parsing with lookup tables built at startup
• Hidden binaries support system maintenance tasks while keeping user help focused

Frequently Asked Questions

How does Omarchy know which commands require root access?

Omarchy reads the requires-sudo metadata flag from each binary's comment headers. The bin/omarchy dispatcher checks this value in register_command (lines 104‑112) and validates privileges before execution (lines 61‑64). No file permissions or external configuration files are needed.

Can I add custom commands to Omarchy without modifying core files?

Yes. Create any executable file named bin/omarchy-<your-command> with appropriate metadata headers. The load_commands function scans the bin/ directory automatically. Your command appears in help output and routing tables immediately — no restart or registry update required.

Where is the source code for the command routing logic?

The main dispatcher implementation lives in bin/omarchy at the repository root. Key functions include load_commands (directory scanning), register_command (metadata parsing), and resolve_route / resolve_direct_route (runtime lookup). The specific line ranges are 17‑20 for scanning and 104‑120 for registration logic.

Why are some Omarchy commands hidden from the default help output?

System‑level binaries use hidden=true to reduce interface clutter. These commands (like bin/omarchy-apply-system) require root privileges and target administrators rather than daily users. The --all flag on omarchy commands reveals these for comprehensive discovery.

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