# How CLI Command Metadata Comments Like # omarchy:hidden Affect Routing in Omarchy

> Learn how # omarchy:hidden metadata comments impact Omarchy routing. Discover how to hide commands from listings while ensuring normal direct invocation.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: internals
- Published: 2026-08-20

---

**CLI command metadata comments like `# omarchy:hidden=true` hide commands from automatic listings and help output without blocking execution—the dispatcher still routes direct invocations normally.**

Omarchy's command-line interface uses special comment annotations at the top of executables in `bin/` to control routing behavior and user-facing documentation. These metadata comments are parsed by the central dispatcher and drive everything from group listings to help generation, making them a powerful tool for managing command visibility.

## How the Metadata Parser Works

The **dispatcher script `bin/omarchy`** scans each command file for lines beginning with `# omarchy:`. Around line 27, a comment-parsing loop extracts **key/value pairs** and stores them in an associative array called `COMMAND_METADATA`. This table powers all subsequent routing decisions.

When you add `# omarchy:hidden=true` to a command file, the parser records the flag and uses it to filter display logic throughout the system.

## What # omarchy:hidden=true Actually Does

The `hidden` flag affects **listing visibility only**—it does not restrict execution.

| Behavior | Effect |
|----------|--------|
| **Group listings** | Hidden commands excluded from `GROUP_DESCRIPTIONS` |
| **Help output** | Hidden commands omitted from `omarchy help` |
| **Direct invocation** | Command executes normally when called explicitly |

This design lets developers keep experimental or internal commands available without cluttering the primary interface.

## Complete Metadata Ecosystem

Omarchy recognizes several metadata comments beyond `hidden`:

- **`# omarchy:summary=…`** – Sets the command description shown in listings

- **`# omarchy:group=…`** – Associates the command with a functional group

- **`# omarchy:requires=…`** – Declares prerequisite commands

- **`# omarchy:hidden=true`** – Suppresses from automatic listings

All follow the same parsing pattern in `bin/omarchy`.

## Working Example

Here's a hidden command definition:

```bash

# File: bin/omarchy-demo

# omarchy:summary=Demo command for illustration

# omarchy:hidden=true

# omarchy:group=dev

echo "Running the hidden demo command"

```

Direct execution works normally:

```bash
$ omarchy demo
Running the hidden demo command

```

But the command disappears from listings:

```bash
$ omarchy help

# "demo" does not appear in output

```

To reveal hidden commands temporarily:

```bash
$ omarchy --show-hidden help

# Now "demo" appears with other hidden commands

```

## GUI Parity: Desktop Entry Handling

Omarchy maintains consistent visibility rules across CLI and graphical interfaces. The script **[`shell/services/hidden-entries.sh`](https://github.com/basecamp/omarchy/blob/main/shell/services/hidden-entries.sh)** (lines 36‑74) processes `.desktop` files and interprets `Hidden` or `NoDisplay` keys identically to the CLI metadata. A command hidden via `# omarchy:hidden=true` stays synchronized with its desktop entry representation.

## Key Implementation Files

- **`bin/omarchy`** – Main dispatcher; parses metadata and applies `hidden` filtering during command catalog construction
- **[`shell/services/hidden-entries.sh`](https://github.com/basecamp/omarchy/blob/main/shell/services/hidden-entries.sh)** – Mirrors hidden-command logic for graphical menus via `.desktop` file analysis

## Summary

- Metadata comments starting with `# omarchy:` are parsed by the `bin/omarchy` dispatcher into a `COMMAND_METADATA` table

- `# omarchy:hidden=true` marks commands as hidden without preventing execution

- Hidden commands execute normally when invoked directly but are filtered from `omarchy help` and group listings
- The `--show-hidden` flag temporarily reveals hidden commands
- Desktop entry handling in [`hidden-entries.sh`](https://github.com/basecamp/omarchy/blob/main/hidden-entries.sh) ensures CLI and GUI visibility stay consistent

## Frequently Asked Questions

### Does # omarchy:hidden=true prevent a command from running?

No. The command executes normally when called directly. The flag only filters the command from automatic listings and help output. This lets you iterate on experimental features without exposing them to casual users.

### Where does Omarchy parse these metadata comments?

The parsing loop in **`bin/omarchy`** around line 27 scans each executable in `bin/` for `# omarchy:` prefixed lines. It populates the `COMMAND_METADATA` associative array that subsequent routing logic consults.

### Can users see hidden commands at all?

Yes. Pass `--show-hidden` to `omarchy help` to reveal the full command catalog including hidden entries. This provides an escape hatch for power users while keeping default views clean.

### How does this relate to graphical menus?

The **[`shell/services/hidden-entries.sh`](https://github.com/basecamp/omarchy/blob/main/shell/services/hidden-entries.sh)** script applies equivalent logic to `.desktop` files, checking `Hidden` and `NoDisplay` keys. This ensures commands hidden from the CLI via metadata comments also stay out of GUI menus.