CLI JSON Output & Exit Codes

Every Arcana CLI command supports --json for machine-readable output and returns deterministic exit codes. This makes Arcana safe to use in CI pipelines, automation scripts, and programmatic workflows.

JSON Output

Add --json to any command to get structured JSON output instead of human-readable text:

# Session list as JSON
arcana session list --json

# Doctor check as JSON
arcana doctor --json

# Model list as JSON
arcana models --json

# Trust status as JSON
arcana trust --json

JSON Structure

All JSON responses follow a consistent envelope:

{
  "ok": true,
  "command": "session list",
  "data": {
    "sessions": [...]
  },
  "meta": {
    "version": "0.4.0",
    "timestamp": "2026-08-19T12:00:00Z"
  }
}

On error:

{
  "ok": false,
  "command": "run",
  "error": {
    "code": "ARC_AUTH_INVALID",
    "message": "Provider API key is invalid or missing",
    "hint": "Set OPENAI_API_KEY or run arcana providers"
  }
}

Exit Codes

Exit codes are deterministic and stable across versions. Use them in CI to distinguish failure modes:

CI Usage

GitHub Actions

- name: Run code review
  run: |
    result=$(arcana run --json --timeout 120 "review this PR for bugs")
    echo "$result" | jq .
    exit_code=$?
    if [ $exit_code -ne 0 ]; then
      echo "::error::Arcana failed with exit code $exit_code"
      exit $exit_code
    fi

Bash Script

#!/bin/bash
set -euo pipefail

# Run with JSON output
output=$(arcana run --json "explain this codebase")

# Check exit code
case $? in
  0)  echo "Success" ;;
  10) echo "Need to login: arcana console login"; exit 1 ;;
  21) echo "Rate limited, retrying in 60s..."; sleep 60 ;;
  *)  echo "Failed: $output"; exit 1 ;;
esac

# Parse JSON
echo "$output" | jq -r '.data.response'

Pipeline Gate

# Use exit codes to gate deployments
arcana run --json "run test suite" || {
  code=$?
  if [ $code -eq 41 ]; then
    echo "Approval required — check the TUI"
  elif [ $code -eq 22 ]; then
    echo "Quota exhausted — add credits"
  fi
  exit $code
}

Error Codes

Error codes are stable strings that appear in JSON output and can be used for programmatic handling:

NDJSON Streaming

For long-running commands, use --ndjson to get newline-delimited JSON events as they happen:

arcana run --ndjson "review this codebase" | while read -r line; do
  event=$(echo "$line" | jq -r '.type')
  case $event in
    "token")   echo -n "$(echo "$line" | jq -r '.data.text')" ;;
    "tool")    echo "[tool: $(echo "$line" | jq -r '.data.name')]" ;;
    "done")    echo ""; echo "Complete. Cost: $(echo "$line" | jq -r '.data.cost')" ;;
  esac
done

Related