How to Get the Omarchy Command List as JSON Output

Run omarchy --json (or omarchy -j) to export the complete command list as structured JSON to stdout.

Omarchy, Basecamp’s open-source CLI framework, provides a built-in mechanism to serialize its command inventory for programmatic consumption. By invoking the main dispatcher with the --json flag, users can retrieve a machine-readable representation of all available commands, their groups, and metadata without parsing human-readable help text.

Using the --json Flag to Export Commands

The primary interface for JSON output is the --json (short -j) option on the main omarchy binary located at bin/omarchy. When detected, the dispatcher bypasses normal execution and instead aggregates metadata from the GROUP_DESCRIPTIONS table defined within the same file.

Basic JSON Output

To dump the entire command catalog as JSON:

omarchy --json

Or using the short form:

omarchy -j

This outputs a single JSON object containing nested arrays of command groups and individual command definitions to stdout.

Filtering by Command Group

You can scope the JSON payload to a specific functional area using the --group flag. This filters the output before serialization, reducing payload size when you only need a subset of commands:

omarchy --json --group capture

This example returns only the commands belonging to the "capture" group (screenshots, recordings, etc.), as defined in the dispatcher’s routing table.

Saving and Processing Output

Because the JSON is emitted to stdout, you can pipe it to jq for pretty-printing or query specific fields:

omarchy --json | jq '.groups[] | select(.prefix == "toggle")'

To persist the command list to a file for offline documentation or IDE integration:

omarchy --json > omarchy-commands.json

Understanding the JSON Structure

The generated JSON follows a predictable schema derived from the internal GROUP_DESCRIPTIONS array in bin/omarchy. The payload organizes commands hierarchically by functional group.

Example truncated payload:

{
  "groups": [
    {
      "prefix": "capture",
      "description": "screenshots, screen recordings, and other capture tools",
      "commands": [
        {
          "name": "omarchy-capture-screenshot",
          "hidden": false,
          "summary": "Take a screenshot of the active window",
          "usage": "omarchy capture screenshot [options]"
        },
        {
          "name": "omarchy-capture-record",
          "hidden": false,
          "summary": "Record the screen to a video file",
          "usage": "omarchy capture record [options]"
        }
      ]
    }
  ]
}

Key fields include:

• groups: Array of functional categories.
• prefix: The namespace or group identifier (e.g., "capture", "toggle").
• commands: Array of executable scripts located in bin/omarchy-*.
• hidden: Boolean flag indicating whether the command should appear in help menus.
• usage: Human-readable invocation pattern.

Implementation Details

According to the Omarchy source code, JSON generation is handled by the main dispatcher script at bin/omarchy. When the --json argument is present, the script calls the omarchy-metadata helper (also in bin/omarchy-metadata) to read the GROUP_DESCRIPTIONS table and format each command’s metadata. This ensures that both the standard help text and the JSON export share the same source of truth.

The individual command scripts in bin/omarchy-* each embed their own help text and contribute to the metadata table, allowing the dispatcher to build the JSON representation dynamically without hard-coding command lists.

Summary

• Invoke JSON mode with omarchy --json or omarchy -j to get the full command list as JSON.
• Filter results by appending --group <prefix> to limit output to specific functional areas.
• Process output using standard Unix pipes (| jq) or redirect to files (> commands.json).
• Source of truth is the GROUP_DESCRIPTIONS table in bin/omarchy, ensuring JSON output stays synchronized with CLI help text.
• Key files: bin/omarchy (dispatcher), bin/omarchy-metadata (formatter), and bin/omarchy-* (individual command scripts).

Frequently Asked Questions

What flag produces JSON output in Omarchy?

The --json flag (or -j shorthand) instructs the bin/omarchy dispatcher to serialize the command inventory as JSON instead of executing a subcommand. This flag is parsed before any command routing occurs.

Where is the command metadata defined?

Command metadata originates from the GROUP_DESCRIPTIONS associative array defined in bin/omarchy. This table maps group prefixes to descriptions and references the individual bin/omarchy-* scripts, which contain their own help strings and usage patterns.

Can I filter the JSON output to specific command groups?

Yes. Append --group <prefix> alongside --json. For example, omarchy --json --group capture returns only the JSON nodes for the capture group, omitting all other categories from the output.

How do I pretty-print the Omarchy JSON output?

Pipe the output to jq . or any JSON formatter. The raw output from omarchy --json is compact; running omarchy --json | jq . produces indented, colorized JSON suitable for terminal reading or further processing.

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