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

> Discover how omarchy command metadata comments drive CLI routing. Learn how these comments auto-generate the routing table to map commands to scripts, simplifying your workflow.

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

---

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

```bash
#!/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](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-transcode-ascii#L3-L7)):

```bash

# 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](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy)) |

| `bin/omarchy-windows-vm` | Full metadata example with `summary`, `args`, `requires-sudo`, `heredoc-expands` ([source](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-windows-vm#L3-L5)) |
| `bin/omarchy-transcode-ascii` | Grouping demonstration with `group=transcode`/`name=ascii` ([source](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-transcode-ascii#L3-L7)) |
| [`AGENTS.md`](https://github.com/omacom/omarchy/blob/main/AGENTS.md) | Architecture documentation covering routing implementation ([source](https://github.com/omacom/omarchy/blob/quattro/AGENTS.md)) |

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