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

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

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

# 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

# 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

# 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

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

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