# How to Get JSON Output from the Omarchy CLI: A Complete Guide

> Easily get JSON output from the Omarchy CLI. Append --json to any command for machine-readable data. Your complete guide to Omarchy CLI JSON output.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: how-to-guide
- Published: 2026-09-02

---

**Append `--json` to any Omarchy CLI command to receive machine-readable JSON output instead of human-readable text.**

The Omarchy command-line interface provides a built-in JSON mode that transforms help text, command lists, and argument descriptions into structured data. This feature is implemented directly in the core Bash script, making it ideal for automation, scripting, and integration with tools like `jq`.

## Understanding the `--json` Flag Mechanism

The Omarchy CLI is built around the single **`omarchy`** Bash script located in `bin/omarchy`. When parsing arguments, the script checks for the `--json` token using the helper function `remaining_has_json_flag` (lines 39-46):

```bash

# From bin/omarchy#L39-L46

remaining_has_json_flag() {
  local remaining=("$@")
  for arg in "${remaining[@]}"; do
    [[ "$arg" == "--json" ]] && return 0
    [[ "$arg" == "--" ]] && break
  done
  return 1
}

```

If `--json` appears anywhere before a `--` separator, the router switches from human-readable output to a JSON document containing route, binary, group, flags, and arguments. This behavior is documented in [`docs/cli-router.md`](https://github.com/omacom/omarchy/blob/main/docs/cli-router.md) (lines 72-113) and validated by the test suite in `test/cli` (lines 66-73).

## Common Commands That Support JSON Output

| Command | JSON Output Description | Source Location |
|---------|------------------------|-----------------|
| `omarchy commands [--all] --json` | Full list of all commands with metadata | `bin/omarchy#L523-L557` |
| `<any command> --json` | JSON description of that specific command | CLI router logic |
| `<any command> --help --json` | Help text rendered as JSON | `docs/cli-router.md#L72-L73` |

## Practical Code Examples

### List All Commands as JSON

```bash

# Get every Omarchy command in machine-readable format

omarchy commands --json | jq '.commands | length'

```

This outputs the total count of available commands. Add `--all` to include internal or hidden commands.

### Inspect a Specific Command's Structure

```bash

# Get JSON description of the 'bar set' command

omarchy bar set my.id background "#ff0000" --json \
  | jq '.flags, .args, .summary'

```

This extracts the flags, arguments, and summary for programmatic inspection.

### Combine Help with JSON Output

```bash

# Render help text as JSON

omarchy parenthelp "explain --json output" --help --json \
  | jq '.ok, .message'

```

Use this pattern when a command accepts both `--help` and other arguments.

### Scripting: Verify Command Existence Before Execution

```bash

# Check if 'omarchy-update' exists before running it

if omarchy commands --json | jq -e '.commands[] | select(.binary=="omarchy-update")' >/dev/null; then
    omarchy update
fi

```

This pattern prevents errors in automation scripts by validating command availability.

## Key Implementation Files

Understanding the source structure helps debug JSON output issues:

- **`bin/omarchy`** — Core Bash script that parses arguments, detects `--json`, and emits JSON for commands and help output.
- **[`docs/cli-router.md`](https://github.com/omacom/omarchy/blob/main/docs/cli-router.md)** — Documentation of CLI routing logic, including the `--json` flag behavior.
- **`test/cli`** — Automated tests validating JSON output format and correctness.
- **[`manual/14-omarchy-cli.md`](https://github.com/omacom/omarchy/blob/main/manual/14-omarchy-cli.md)** — User-facing documentation mentioning `--json` for the `commands` sub-command.

## JSON Output Schema

While the exact schema varies by command, JSON responses typically include:

- **route** — The command path (e.g., `["bar", "set"]`)
- **binary** — The underlying executable name
- **group** — Functional category for organization
- **flags** — Available command-line flags with descriptions
- **args** — Positional arguments with types and requirements
- **summary** — Human-readable command description

No external services are required—JSON generation happens entirely within the `omarchy` script.

## Summary

- Append `--json` before any `--` separator to enable JSON mode in the Omarchy CLI.
- The `remaining_has_json_flag` function in `bin/omarchy` (lines 39-46) detects this flag.
- Primary use cases: `commands --json` for listing, `<command> --json` for description, and `<command> --help --json` for help text.
- Pipe output to `jq` for filtering, counting, or transforming JSON data.
- All JSON generation is local—no network dependencies.

## Frequently Asked Questions

### Can I combine `--json` with other flags?

Yes. Place `--json` before any `--` separator. Flags after `--` are passed to the target command unchanged. For example: `omarchy commands --all --json` works, but `omarchy commands -- --json` treats `--json` as a command argument instead of a CLI flag.

### What happens if a command doesn't support JSON?

All Omarchy CLI commands route through the same parser in `bin/omarchy`. The `--json` flag is handled at the router level, so every command can potentially emit JSON metadata. However, the usefulness varies—some internal commands may return minimal descriptors.

### Is the JSON schema stable for scripting?

The schema is documented in [`docs/cli-router.md`](https://github.com/omacom/omarchy/blob/main/docs/cli-router.md) and tested in `test/cli`. While core fields like `route`, `binary`, and `flags` are stable, always validate JSON with `jq` or similar tools in production scripts to handle potential additions.

### How do I handle JSON output in shell scripts without `jq`?

Use Bash's built-in JSON parsing with `grep`, `sed`, or `awk` for simple extractions. For robust parsing, install `jq`—it's the recommended tool referenced throughout Omarchy's test suite and documentation.