How Omarchy Handles Hidden Commands in Its CLI: Metadata Parsing and Filter Logic

Omarchy treats hidden commands as standard executables that are filtered from default help listings by parsing # omarchy:hidden=true metadata during registration and checking the COMMAND_HIDDEN associative array before displaying output.

Omarchy's command-line interface provides a streamlined developer experience by allowing certain utilities to remain accessible yet invisible in standard command listings. Understanding how hidden commands are registered, stored, and filtered reveals the elegant metadata-driven architecture implemented in the central dispatcher.

Parsing Hidden Command Metadata During Registration

When Omarchy initializes, the register_command function scans each command script for structured metadata comments. According to the source code in bin/omarchy, this parsing occurs at lines 34–38, where the system specifically looks for the hidden key within metadata blocks.

Each command script can declare its visibility status using a dedicated comment directive:

# omarchy:hidden=true

The registration logic validates that the hidden value is either omitted or exactly "true". If the metadata specifies true, the function immediately stores this flag alongside other command attributes like group, name, and summary.

Storing Visibility Flags in COMMAND_HIDDEN

Omarchy maintains command metadata using associative arrays declared at the top of bin/omarchy. The hidden status is preserved in the COMMAND_HIDDEN array, defined at line 20:

declare -A COMMAND_HIDDEN

When register_command processes a script containing the hidden directive, it assigns the value to COMMAND_HIDDEN[$key], where $key represents the command's internal identifier (typically formatted as group_name). This storage mechanism keeps the visibility flag tightly coupled with the command's registry entry without affecting the command's executable permissions or routing logic.

Filtering Hidden Commands from CLI Output

The actual hiding mechanism occurs during list generation, not command execution. Omarchy builds command listings through two primary sorting functions that respect the hidden flag unless explicitly overridden.

Conditional Filtering in sorted_keys

The sorted_keys function (lines 17–20 of bin/omarchy) iterates through registered commands and conditionally skips entries where COMMAND_HIDDEN[$key] equals "true". This filtering happens before generating the sorted output for omarchy commands, ensuring that hidden utilities never appear in default help views.

Group-Level Filtering in sorted_group_keys

Similarly, the sorted_group_keys function (lines 63–65) applies identical filtering logic when organizing commands by their functional groups. This ensures consistency across both flat and grouped command listings, maintaining a clean interface that surfaces only the commands relevant to typical daily workflows.

Exposing Hidden Commands with the --all Flag

Power users can override the filtering mechanism using the --all option. When executing omarchy commands --all, the CLI invokes parse_commands_args (lines 48–55), which sets a flag that propagates through to the sorting functions. This parameter causes both sorted_keys and sorted_group_keys to bypass the COMMAND_HIDDEN check, displaying the complete command inventory including internal or experimental tools.

The help text for this functionality is documented at lines 91–95 in bin/omarchy, clearly indicating that the --all flag reveals commands marked with hidden metadata.

Implementing Hidden Commands in Practice

Creating a hidden command requires adding the metadata directive near the top of the script file. For example, a secret development tool stored at bin/omarchy-dev-secret would include:

#!/usr/bin/env bash

# omarchy:hidden=true

# omarchy:group=dev

# omarchy:name=secret

# omarchy:summary=Runs a secret internal tool

echo "Executing secret operation..."

Despite being hidden from omarchy commands output, the command remains fully executable via its direct route:

# Hidden from default listing

$ omarchy commands
Omarchy commands:
  omarchy update                 Update Omarchy and system packages
  omarchy theme list            List available themes

# Revealed with --all flag

$ omarchy commands --all
Omarchy commands (all):
  omarchy dev secret            Runs a secret internal tool
  omarchy update                Update Omarchy and system packages

# Execute directly without --all

$ omarchy dev secret
Executing secret operation...

Summary

• Metadata parsing: The register_command function in bin/omarchy (lines 34–38) scans scripts for # omarchy:hidden=true directives during initialization.

• Flag storage: Hidden status is stored in the COMMAND_HIDDEN associative array (declared line 20) using the command's internal key.

• List filtering: Both sorted_keys (lines 17–20) and sorted_group_keys (lines 63–65) skip hidden commands unless the --all flag is provided.

• Direct execution: Hidden commands remain fully functional and executable via their full route (omarchy <group> <command>) regardless of visibility settings.

• Override mechanism: The omarchy commands --all invocation (handled in parse_commands_args at lines 48–55) displays the complete command inventory.

Frequently Asked Questions

How do I mark a command as hidden in Omarchy?

Add the metadata comment # omarchy:hidden=true near the top of your command script, typically alongside other Omarchy directives like # omarchy:group and # omarchy:name. The register_command function in bin/omarchy will detect this flag during CLI initialization and set the corresponding value in the COMMAND_HIDDEN associative array.

Can hidden commands still be executed normally?

Yes. Hidden commands remain fully executable via their direct route (omarchy <group> <command>). The hidden flag only affects visibility in command listings generated by omarchy commands; it does not impact the dispatcher's ability to resolve and execute the script.

Where is the hidden command flag stored internally?

The hidden status is stored in the COMMAND_HIDDEN associative array, declared at line 20 of bin/omarchy. Each command's internal key maps to either "true" or an empty value, which the sorting functions check at lines 17–20 (sorted_keys) and 63–65 (sorted_group_keys) before including the command in help output.

How do I list all commands including hidden ones?

Append the --all flag to the commands sub-command: omarchy commands --all. This passes a visibility override to the sorting functions (sorted_keys and sorted_group_keys), causing them to bypass the COMMAND_HIDDEN filter and display the complete inventory of available commands.

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