How to List Non-Hidden Commands in Omarchy

Run omarchy without arguments to display only visible commands, or use omarchy --list | jq -r '.commands[] | select(.hidden == false) | .name' to generate a programmatic list of non-hidden entries.

Omarchy, Basecamp's open-source CLI framework, organizes functionality into discrete command scripts stored in the bin/ directory. Each script declares its visibility status via metadata comments that the central dispatcher parses to determine which commands appear in the default help output. Understanding this metadata system is essential when you need to list non-hidden commands in Omarchy for automation or discovery.

Understanding Omarchy's Command Metadata Structure

Omarchy stores each CLI command as an individual executable script inside the bin/ directory following the omarchy-* naming convention. At the top of every command script, the framework recognizes special metadata pragmas that control how the command is categorized and displayed:

# omarchy:group=theme

# omarchy:hidden=true

The # omarchy:hidden=true flag specifically instructs the dispatcher to exclude that command from default listings. When this metadata is absent or set to false, the command is considered visible and will appear in standard output.

Listing Non-Hidden Commands via the CLI

The central dispatcher script located at bin/omarchy provides two primary methods for viewing command inventory: human-readable help and structured JSON output.

Human-Readable Help Output

To see only the commands that are not hidden, invoke the dispatcher without any extra options:

omarchy

This executes the default behavior of bin/omarchy, which scans every omarchy-* file in the bin/ directory, parses their metadata headers, and renders a grouped list excluding any command marked with hidden=true.

Machine-Readable JSON Export

For automation and scripting, Omarchy supports a --list flag that serializes all command metadata to JSON. You can pipe this output to jq to filter out hidden entries:

omarchy --list | jq -r '.commands[] | select(.hidden == false) | .name'

This command queries the JSON structure generated by bin/omarchy, selecting only objects where the hidden property is false and extracting the command names.

Programmatic Filtering Examples

When building shell functions or automation scripts that need to iterate over visible commands only, wrap the JSON filtering logic in a reusable function:

list_visible_commands() {
    omarchy --list | jq -r '.commands[] | select(.hidden == false) | .name'
}

# Usage

for cmd in $(list_visible_commands); do
    echo "Processing: $cmd"
done

This approach ensures your scripts always reference the current set of non-hidden commands as defined in the repository's bin/ directory.

How the Dispatcher Identifies Hidden Commands

The logic that distinguishes hidden from visible commands resides in bin/omarchy, which acts as the entry point for all Omarchy CLI operations. When building the command registry, the dispatcher reads the metadata headers from each omarchy-* script and constructs an internal representation of the command's properties. Commands containing the hidden=true metadata are omitted from the default help rendering but remain accessible if invoked directly by name.

The framework maintains consistency with desktop environment integration through shell/services/hidden-entries.sh, which applies similar visibility logic to desktop entry files, ensuring that hidden commands are suppressed across both terminal and graphical interfaces.

Summary

• Command Location: Individual commands are stored as scripts in the bin/ directory with the omarchy-* prefix.

• Metadata Flag: The comment # omarchy:hidden=true marks a command as hidden in the source file.

• Default Listing: Running omarchy without arguments displays only non-hidden commands by parsing these metadata headers.

• JSON Filtering: Use omarchy --list combined with jq 'select(.hidden == false)' for programmatic access to visible command names.

• Dispatcher Logic: The bin/omarchy script handles the parsing and filtering logic that drives both human-readable and machine-readable output formats.

Frequently Asked Questions

What makes an Omarchy command "hidden"?

A command is considered hidden when its script file contains the metadata comment # omarchy:hidden=true at the top. This flag tells the central dispatcher in bin/omarchy to exclude the command from default help listings while keeping it available for direct invocation.

Where are Omarchy commands physically stored?

All commands reside as individual executable scripts in the bin/ directory, prefixed with omarchy- (for example, bin/omarchy-theme-list). Each script may contain metadata headers that define its group assignment and visibility status.

Can I list hidden commands if I need to debug?

Yes. When using the JSON export mode with omarchy --list, the output includes all commands regardless of their hidden status. You can view hidden entries specifically by modifying the jq filter to select(.hidden == true) or by examining the raw JSON output directly.

Does Omarchy apply hiding logic to desktop applications?

Yes. According to the source code in shell/services/hidden-entries.sh, Omarchy uses similar visibility detection for desktop entry files, ensuring that commands marked as hidden are consistently suppressed across both the terminal interface and graphical application menus.

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