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

> Discover how Omarchy manages hidden commands by parsing metadata and filtering entries. Learn to reveal all commands with the --all flag.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: internals
- Published: 2026-09-04

---

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

```bash

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

```bash

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

```bash

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

```bash

# 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

```bash
#!/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:

```bash

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