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

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:

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

$ omarchy demo
Running the hidden demo command

But the command disappears from listings:

$ omarchy help

# "demo" does not appear in output

To reveal hidden commands temporarily:

$ 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 (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 – 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 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 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.

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