How Hidden Commands Are Managed in Omarchy: Metadata Parsing and Filtering Explained

Omarchy hides commands by parsing the metadata comment # omarchy:hidden=true in script headers, storing the flag in the COMMAND_HIDDEN associative array, and filtering these entries from default command listings unless the --all flag is explicitly provided.

Omarchy is an opinionated desktop environment built on Arch Linux that uses a metadata-driven command system. Understanding how hidden commands work in omarchy requires examining the core dispatcher logic and the specific parsing rules that determine command visibility.

How Omarchy Defines Hidden Commands

Omarchy treats a command as hidden when its script contains a specific metadata comment directive. This system allows developers to include utility scripts in the bin/ directory while keeping them invisible to casual users.

Metadata Parsing in bin/omarchy

The main dispatcher located at bin/omarchy handles the detection and classification of hidden commands during the initial scan of the bin/ directory. When parsing script metadata, the dispatcher looks for the key-value pair hidden="$metadata_value" extracted from comments.

According to the source code in bin/omarchy around line 236, the parser extracts the hidden attribute and validates that the value is either omitted or exactly true (line 237). If the validation fails, the parser raises an error. When valid, the boolean value is stored in the COMMAND_HIDDEN associative array.

# Example metadata block in a command script

#!/usr/bin/env bash

# omarchy:hidden=true

# omarchy:group=toggle

# omarchy:name=nightlight

# omarchy:summary=Toggle night-light

Where Hidden Command Data Is Stored

The visibility state persists in the COMMAND_HIDDEN associative array indexed by command key. As implemented in bin/omarchy around line 279, if a command is marked as hidden, COMMAND_HIDDEN["$key"] is set to "true"; otherwise, it defaults to "false".

This storage mechanism allows the dispatcher to perform constant-time lookups when building command lists or executing help functionality. The array is populated during the initialization phase before any user interaction occurs.

Filtering Hidden Commands in Practice

The omarchy CLI uses the COMMAND_HIDDEN array to determine which commands appear in user-facing outputs.

Default Command Listing

When you run omarchy commands without arguments, the dispatcher iterates through available commands and excludes any entry where COMMAND_HIDDEN["$key"] equals "true". This ensures that administrative or experimental utilities remain out of the default menu.

# List only visible commands (hidden commands excluded)

$ omarchy commands

# Output shows only non-hidden commands

Exposing Hidden Commands with --all

To reveal hidden utilities, omarchy supports the --all flag. As documented in the help text around line 542 in bin/omarchy, passing this flag forces the inclusion of hidden commands in the output.

# Show all commands including hidden ones

$ omarchy commands --all

# Output now includes commands marked with # omarchy:hidden=true

A practical example of a hidden command is bin/omarchy-update-status, which contains the metadata comment # omarchy:hidden=true to prevent it from cluttering the standard command menu while remaining accessible for system integrations.

Hidden Desktop Entries

Omarchy extends the hidden-entry concept beyond CLI commands to desktop environment entries. The helper script shell/services/hidden-entries.sh implements the is_hidden_desktop_file function (line 71) that reads the Hidden= key inside .desktop files.

When the launcher processes applications, it calls is_hidden_desktop_file to filter entries where Hidden=true. This maintains consistency between the CLI command visibility and the graphical application menu.

# Logic from shell/services/hidden-entries.sh

is_hidden_desktop_file() {
    local file=$1
    local hidden=false
    # Parse the .desktop file for Hidden= key

    [[ $hidden == "true" ]] && return 0   # Entry is hidden

    return 1                               # Entry is visible

}

Complete Implementation Example

To mark a new command as hidden in your omarchy installation:

1. Create a script in the bin/ directory
2. Add the metadata comment at the top
3. The dispatcher automatically handles the rest

#!/usr/bin/env bash

# omarchy:hidden=true

# omarchy:group=system

# omarchy:name=internal-sync

# omarchy:summary=Sync internal caches (hidden utility)

echo "Syncing..."

Access the hidden command using:

# Direct execution works regardless of visibility

$ omarchy internal-sync

# Or discover it via --all flag

$ omarchy commands --all | grep internal-sync

Summary

• Metadata Marker: Hidden commands are defined by the comment # omarchy:hidden=true in script headers

• Core Parser: The bin/omarchy dispatcher extracts this metadata and populates the COMMAND_HIDDEN associative array

• Validation: Values must be exactly true or omitted; invalid values trigger parser errors

• Default Filter: Standard omarchy commands output excludes entries where COMMAND_HIDDEN["$key"]="true"

• Override Flag: The --all flag includes hidden commands in listings

• Desktop Parity: shell/services/hidden-entries.sh applies identical logic to .desktop files via is_hidden_desktop_file

Frequently Asked Questions

How do I mark a command as hidden in omarchy?

Add the metadata comment # omarchy:hidden=true to the top of your script in the bin/ directory, alongside other omarchy metadata fields like # omarchy:group= and # omarchy:name=. The bin/omarchy dispatcher automatically detects this flag during initialization.

Why can I still run a hidden command directly even though it is hidden?

Hidden status only affects discovery and listing through omarchy commands, not execution. The hidden flag filters the command from the default menu to reduce clutter, but the script remains executable via omarchy <command-name> or direct path invocation.

Where does omarchy store the hidden status of commands?

The hidden status is stored in the COMMAND_HIDDEN associative array within the main bin/omarchy dispatcher. This array is populated at startup by parsing the metadata headers of all scripts in the bin/ directory, with keys set to "true" for hidden commands and "false" for visible ones.

Does omarchy hide desktop applications the same way it hides CLI commands?

Yes, the concept is parallel but implemented separately. While CLI commands use # omarchy:hidden=true parsed by bin/omarchy, desktop files use the standard Hidden=true key parsed by shell/services/hidden-entries.sh in the is_hidden_desktop_file function. Both systems prevent hidden items from appearing in their respective interfaces unless explicitly revealed.

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