# How to Get the Omarchy Command List as JSON Output

> Effortlessly export your omarchy command list as JSON using the simple --json flag. Get structured output for seamless integration with your tools.

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

---

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

```bash
omarchy --json

```

Or using the short form:

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

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

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

```

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

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

```json
{
  "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.