# How to List All Available Omarchy Commands: Complete CLI Reference

> Easily list all available omarchy commands with `omarchy commands`. Access a complete CLI reference for the basecamp/omarchy repository and enhance your workflow.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: api-reference
- Published: 2026-08-26

---

**Run `omarchy commands` to display a formatted table of every available command registered in the `bin/` directory.**

The `basecamp/omarchy` repository provides a centralized command-center that automatically discovers and registers scripts following the `omarchy-*` naming convention. Understanding how to list all available omarchy commands helps you navigate the CLI efficiently and integrate the tool into your development workflow.

## Understanding the Command Discovery Mechanism

Omarchy employs a dynamic discovery system that scans the `bin/` directory for executable scripts matching the `omarchy-*` pattern.

### How Commands Are Registered

The `load_commands` function in `bin/omarchy` (lines 13-20) iterates through the local `bin/` directory to locate every file prefixed with `omarchy-`. This function registers metadata—including group classification, command name, and summary description—for each executable binary it encounters.

When you invoke the main dispatcher, the `main()` function handles routing via a dispatch table defined at lines 77-84, directing execution to the appropriate handler when you call the `commands` sub-command.

## Listing Available Commands

The primary interface for viewing registered commands is the `commands` sub-command itself.

### Basic Usage

To generate a human-readable list of all visible commands, execute:

```bash
omarchy commands

```

This invokes the `show_commands` function (lines 83-95 in `bin/omarchy`), which iterates over sorted routes and prints a formatted table to your terminal.

### Output Structure

The default output organizes commands by their registered groups and includes:

- Command route and name
- Brief summary description
- Group classification for categorization

## Command Options and Flags

The `omarchy commands` sub-command supports several flags parsed by `parse_commands_args` (lines 38-73 in `bin/omarchy`) to customize or validate the output.

### Filtering Hidden Commands

By default, commands marked as hidden are excluded from standard listings. To reveal all commands including internal utilities, append the `--all` flag:

```bash
omarchy commands --all

```

### Alternative Output Formats

For programmatic access or documentation generation, request structured output instead of the default table:

```bash

# Machine-readable JSON for scripts

omarchy commands --json

# Markdown table for documentation

omarchy commands --markdown

```

### Validation Checks

Before deploying new commands or committing changes, verify registry integrity:

```bash
omarchy commands --check

```

This runs a validation pass that checks for route collisions, missing metadata fields, and ensures all discovered binaries maintain proper executable permissions.

## Practical Code Examples

Here are common patterns for interacting with the command registry:

```bash

# View all user-facing commands

omarchy commands

# Include internal/hidden utilities

omarchy commands --all

# Export command structure for automation

omarchy commands --json > omarchy-commands.json

# Generate documentation table for README

omarchy commands --markdown

# Validate metadata before releases

omarchy commands --check

```

## Summary

- **Entry point**: The `commands` sub-command in `bin/omarchy` serves as the primary interface for listing available commands.
- **Discovery**: The `load_commands` function automatically registers every executable `omarchy-*` script found in the `bin/` directory.
- **Formatting**: Use `--json` for programmatic parsing or `--markdown` for documentation workflows.
- **Validation**: The `--check` flag ensures metadata integrity and prevents route conflicts.
- **Visibility**: Hidden commands require the `--all` flag to appear in listings.

## Frequently Asked Questions

### How does Omarchy discover new commands?

Omarchy scans the `bin/` directory for any executable file matching the `omarchy-*` naming pattern. The `load_commands` function in `bin/omarchy` (lines 13-20) handles this registration automatically, extracting metadata such as group classification and summary descriptions from each binary.

### What is the difference between `omarchy commands` and `omarchy commands --all`?

The default `omarchy commands` output excludes utilities explicitly marked as hidden in their metadata. Adding the `--all` flag forces the `show_commands` function to include these hidden entries, revealing administrative or internal tools not intended for standard user workflows.

### Can I use the command listing in automation scripts?

Yes. Pass the `--json` flag to `omarchy commands` to receive a structured JSON document describing each registered command's metadata. This machine-readable format is ideal for shell scripts, CI/CD pipelines, and third-party integrations that need to parse available omarchy capabilities programmatically.

### Where is the command validation logic implemented?

The `--check` flag logic resides within `parse_commands_args` (lines 38-73) in `bin/omarchy`. This validation routine verifies that no route collisions exist, that all required metadata fields are populated, and that every discovered binary maintains proper executable permissions.