ARCANA
Back to Blog

Tutorial

Scriptable CLI: JSON Output and Deterministic Exit Codes

Jul 15, 2026 Tutorial

Arcana is a TUI first, but it is also a CLI. Every command supports --json output and returns deterministic exit codes. This makes it safe to use in shell scripts, CI pipelines, and automation workflows.

The TUI is where you interact with Arcana conversationally. But many workflows are not conversational. They are scripted. A CI pipeline that runs a code review does not need a terminal UI. A cron job that generates a daily report does not need interactive prompts. For these workflows, the CLI with JSON output is the right interface.

The --json flag is not a separate mode. It is a flag that transforms any command's output from human-readable to machine-readable. The same command, the same logic, the same error handling. Just a different output format.

JSON Output

Any command that produces human-readable output also produces structured JSON with the --json flag:

# Human-readable
arcana stats

# Machine-readable
arcana stats --json

The JSON output follows a consistent schema: a status field, a data object with the actual results, and optionally an error field with structured error information.

Exit Codes

Deterministic exit codes mean you can rely on them in conditionals:

arcana models list --json
if [ $? -eq 0 ]; then
  echo "Models loaded successfully"
elif [ $? -eq 1 ]; then
  echo "Configuration error"
elif [ $? -eq 2 ]; then
  echo "Network error"
fi

Exit code conventions:

  • 0: Success
  • 1: Configuration or input error
  • 2: Network or provider error
  • 3: Authentication error
  • 4: Quota or rate limit error

Shell Completion

Arcana ships shell completions for bash, zsh, and fish on Linux and macOS. On Windows, completions are available for PowerShell.

Linux / macOS:

# Bash
arcana completion bash > ~/.bash_completion.d/arcana

# Zsh
arcana completion zsh > ~/.zsh/completions/_arcana

# Fish
arcana completion fish > ~/.config/fish/completions/arcana.fish

Windows (PowerShell):

# PowerShell
arcana completion powershell > "$env:USERPROFILE\Documents\WindowsPowerShell\Modules\Arcana\Arcana.psm1"

# Or for PowerShell 7+
arcana completion powershell > "$env:USERPROFILE\Documents\PowerShell\Modules\Arcana\Arcana.psm1"

After installing completions, restart your shell or run source ~/.bashrc (bash), source ~/.zshrc (zsh), or . $PROFILE (PowerShell) to activate them.

Practical Examples

Use Arcana in cron jobs, GitHub Actions, or Makefiles. The --timeout flag bounds session duration so scripts do not hang:

# Run a task with a 60-second timeout, capture JSON output
arcana run "summarize this PR" --timeout 60 --json > report.json

Piping and Composition

JSON output composes naturally with tools like jq:

# Get the list of available models as a simple array
arcana models list --json | jq '.data[].name'

# Check if a specific model is available
arcana models list --json | jq -e '.data[] | select(.name == "claude-3.5-sonnet")'

# Extract just the error message from a failed command
arcana models list --json 2>&1 | jq -r '.error.message // empty'

# Count how many models are available
arcana models list --json | jq '.data | length'

The JSON output schema is stable. Once documented, it does not change without a major version bump. This means you can write scripts that depend on specific fields without worrying about breakage.

Error Handling Patterns

Reliable scripts need reliable error handling. Arcana's exit codes make this possible.

Bash (Linux / macOS):

#!/bin/bash
# A robust Arcana CLI script
set -euo pipefail

result=$(arcana run "review this PR" --timeout 120 --json 2>&1)
exit_code=$?

case $exit_code in
  0) echo "$result" | jq -r '.data.summary' ;;
  1) echo "Config error: check your config.json" >&2; exit 1 ;;
  2) echo "Network error: provider may be down" >&2; exit 1 ;;
  3) echo "Auth error: check your API keys" >&2; exit 1 ;;
  4) echo "Quota exhausted: try again later" >&2; exit 1 ;;
  *) echo "Unknown error (exit code $exit_code)" >&2; exit 1 ;;
esac

PowerShell (Windows):

# A robust Arcana CLI script (PowerShell)
$result = arcana run "review this PR" --timeout 120 --json 2>&1
$exitCode = $LASTEXITCODE

switch ($exitCode) {
  0 { $result | ConvertFrom-Json | Select-Object -ExpandProperty data | Select-Object -ExpandProperty summary }
  1 { Write-Error "Config error: check your config.json"; exit 1 }
  2 { Write-Error "Network error: provider may be down"; exit 1 }
  3 { Write-Error "Auth error: check your API keys"; exit 1 }
  4 { Write-Error "Quota exhausted: try again later"; exit 1 }
  default { Write-Error "Unknown error (exit code $exitCode)"; exit 1 }
}

The deterministic exit codes mean you can write scripts that handle each failure mode appropriately instead of treating all errors the same way.

Related Reading