# How Omarchy Handles Hidden Commands in Its CLI: Metadata Parsing and Filter Logic > Discover how Omarchy handles hidden commands in its CLI. Learn about metadata parsing and filter logic to exclude commands from default help listings. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: internals - Published: 2026-08-25 --- **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: ```bash # 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**: ```bash 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: ```bash #!/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: ```bash # 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 `) 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 `). 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.