How Omarchy Command Metadata Comments Influence CLI Routing: A Complete Guide

Omarchy command metadata comments (lines starting with # omarchy:) are parsed at startup to auto-generate the routing table that maps omarchy <group> <command> syntax to executable Bash scripts in bin/.

Omarchy's command-line interface is built from small, single-purpose Bash scripts located in the bin/ directory. Each script begins with specially-formatted comments that serve as both documentation and executable configuration. These command metadata comments eliminate the need for manual command registration—adding a new command is as simple as creating a file with the right comment block.

Understanding the Metadata Comment Format

Every Omarchy command script starts with metadata fields prefixed by # omarchy:. The core dispatcher in bin/omarchy extracts these key-value pairs using a grep-like parser and builds the routing table dynamically.

Core Metadata Fields

Field	Purpose	Example
summary	Short description for help menus	# omarchy:summary=Toggle the "foo" feature on or off

| args | Positional argument validation | # omarchy:args=[on\|off\|toggle] |

| examples | Usage examples in help output | # omarchy:examples=omarchy toggle foo \| omarchy toggle foo --dev |

| requires-sudo | Auto-elevate with sudo/pkexec | # omarchy:requires-sudo=true |

| hidden | Exclude from public command list | # omarchy:hidden=true |

| group / name | Namespace for sub-commands | # omarchy:group=transcode # omarchy:name=ascii |

How Omarchy Command Metadata Drives Routing

The routing process happens in six distinct phases when the omarchy dispatcher starts:

1. Discovery: Scan every executable in bin/ for # omarchy: lines.

2. Extraction: Parse key-value pairs into an associative array keyed by script filename.

3. Menu Generation: Build GROUP_DESCRIPTIONS from summary fields of visible commands (hidden≠true) for the top-level help.

4. Command Resolution: Map omarchy <group> <command> to the matching script, respecting group/name overrides.

5. Privilege Escalation: Auto-wrap execution with sudo or pkexec if requires-sudo=true.

6. Argument Forwarding: Pass remaining CLI arguments to the selected script.

This comment-driven routing means internal utilities and public commands share the same discovery mechanism—only the hidden flag distinguishes them.

Practical Example: Creating a New Command

Here's a complete command that demonstrates metadata influence on routing behavior:

#!/bin/bash

# File: bin/omarchy-toggle-foo

# omarchy:summary=Toggle the "foo" feature on or off

# omarchy:args=[on|off|toggle]

# omarchy:requires-sudo=true

case "${1:-toggle}" in
  on)   echo "Enabling foo…"   ;;
  off)  echo "Disabling foo…"  ;;
  *)    echo "Toggling foo…"   ;;
esac

Placing this in bin/ automatically:

• Registers under the toggle group (derived from omarchy-toggle-foo filename).
• Displays "Toggle the 'foo' feature on or off" in omarchy help.
• Validates arguments against [on|off|toggle].
• Executes with sudo elevation without manual prompt handling.

Grouping Commands with Metadata Overrides

Filename-based grouping has limits. The group and name fields override automatic routing for logical organization.

In bin/omarchy-transcode-ascii (see source):

# omarchy:group=transcode

# omarchy:name=ascii

# omarchy:summary=Convert video to ASCII art

This script appears as omarchy transcode ascii—not omarchy transcode-ascii. The metadata overrides the filename, enabling cleaner CLI organization without renaming files.

Hidden Commands and Internal Routing

Commands marked # omarchy:hidden=true remain fully routable but are excluded from help generation. This supports:

• Internal utilities invoked by other commands.
• Deprecated commands preserved for backward compatibility.
• Administrative functions not exposed to casual users.

The routing table includes hidden commands; only the menu builder filters them.

Key Source Files

File	Role
bin/omarchy	Central dispatcher parsing # omarchy: comments and building routing tables (source)

| bin/omarchy-windows-vm | Full metadata example with summary, args, requires-sudo, heredoc-expands (source) | | bin/omarchy-transcode-ascii | Grouping demonstration with group=transcode/name=ascii (source) | | AGENTS.md | Architecture documentation covering routing implementation (source) |

Summary

• Omarchy command metadata comments in bin/ scripts are the single source of truth for CLI routing.

• The bin/omarchy dispatcher parses # omarchy: lines at startup—no registration code required.

• Metadata fields control grouping, privilege escalation, help generation, and visibility.

• Adding commands is file-driven: create a script with comment metadata, and routing updates automatically.

Frequently Asked Questions

What happens if I omit metadata comments in a bin/ script?

The script remains executable but receives no routing entry. It won't appear in help, won't auto-elevate privileges, and won't validate arguments. The dispatcher may still execute it as a fallback if called directly by filename.

Can metadata comments appear anywhere in the file?

No—they must be at the top of the script before any executable code. The parser uses a simple grep pattern that expects these comments in the header block. Comments later in the file are treated as ordinary documentation and ignored.

How does requires-sudo actually work at execution time?

When requires-sudo=true is detected, the dispatcher in bin/omarchy wraps the script invocation with sudo (or pkexec for graphical environments) before passing arguments. The user receives a standard password prompt, and the script executes with elevated privileges throughout its lifecycle.

Are there performance implications of parsing all bin/ files at startup?

The parsing mechanism uses simple text extraction—no heavy deserialization. For typical Omarchy installations with dozens of commands, startup overhead remains negligible. The routing table is rebuilt on every omarchy invocation, ensuring metadata changes take effect immediately without restart.

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