How to List All Available Omarchy Commands: Complete CLI Reference

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:

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:

omarchy commands --all

Alternative Output Formats

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

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

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:

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

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