# How Omarchy Manages System and Runtime Binaries: A Metadata‑Driven Command System > Discover how Omarchy manages system and runtime binaries with a metadata-driven command system. Learn about its single dispatcher script for efficient binary management. - Repository: [Omacom/omarchy](https://github.com/omacom/omarchy) - Tags: internals - Published: 2026-09-05 --- 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:=`: ```bash #!/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: ```bash #!/usr/bin/env bash # omarchy:group=system # omarchy:summary=Apply system configuration # omarchy:requires-sudo=true # omarchy:hidden=true ``` When a user runs: ```bash 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: ```bash #!/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: ```bash # 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: ```bash # 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-` 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.