# How to List Non-Hidden Commands in Omarchy

> Easily list non-hidden commands in Omarchy. Discover how to view only visible commands or generate a programmatic list with this quick Omarchy guide.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-27

---

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

```bash

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

```bash
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:

```bash
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:

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