Scripting & AutomationNEW

Every sophon command runs non-interactively when you give it a subcommand and arguments — only bare sophon (or sophon chat) opens the REPL. That makes the CLI a thin, scriptable wrapper over the REST API: pick a machine-readable format, check the exit code, and pipe the output anywhere.

JSON output

Pass --json (shorthand for --format json) on any command that lists or describes resources. The default format is table; csv is also available.

sophon models list --json
sophon workflows list --format json
sophon tasks recent --limit 100 --json

JSON goes to stdout with nothing else mixed in, so you can pipe straight to jq:

# Names of every configured model provider
sophon models list --json | jq -r '.[].name'

# IDs of workflows that are currently disabled
sophon workflows list --json | jq -r '.[] | select(.enabled == false) | .id'

# Count failed background tasks in the last 100
sophon tasks recent --limit 100 --json | jq '[.[] | select(.status == "failed")] | length'

Clean logs

CI logs and files don't want ANSI color codes. Disable them with --no-color, or set NO_COLOR=1 (the standard the CLI honors):

sophon status --no-color
NO_COLOR=1 sophon doctor

JSON and CSV output are already plain text, but --no-color also strips color from any incidental warnings or errors.

Exit codes

Every command exits 0 on success and a non-zero code on failure — an unreachable gateway, an auth error, an unknown command, or a 4xx/5xx from the API. Branch on it the usual way:

if sophon health --json > /dev/null; then
  echo "Gateway healthy"
else
  echo "Gateway check failed" >&2
  exit 1
fi

Headless auth

Scripts and CI runners can't log in interactively. Point the CLI at a remote or self-hosted gateway and supply a token through environment variables instead of sophon login:

export SOPHON_GATEWAY_URL="https://gw.example.com"
export SOPHON_AUTH_TOKEN="$SOPHON_TOKEN"   # from your secrets store

sophon doctor
sophon workflows list --json

SOPHON_GATEWAY_URL and SOPHON_AUTH_TOKEN override gatewayUrl / authToken in cli.json, so the same script works locally and in CI without writing credentials to disk. The personal tier needs no token. Full env and config details are in Configuration & Auth.

Shell completions

Generate a completion script with sophon completions <shell>. Supported shells are bash, zsh, fish, and powershell / pwsh. The command prints the script to stdout so you can eval it directly or write it to a file.

# Bash — add to ~/.bashrc
eval "$(sophon completions bash)"

# Zsh — add to ~/.zshrc
eval "$(sophon completions zsh)"

# Fish — save to the completions directory
sophon completions fish > ~/.config/fish/completions/sophon.fish

# PowerShell — add to $PROFILE
sophon completions powershell | Invoke-Expression

Examples

Run diagnostics as a CI gate. sophon doctor checks gateway reachability, auth, providers, channels, Docker, the data directory, and cli.json, and exits non-zero if anything fails:

#!/usr/bin/env bash
set -euo pipefail

export SOPHON_GATEWAY_URL="https://gw.example.com"
export SOPHON_AUTH_TOKEN="$SOPHON_TOKEN"

sophon doctor --no-color

Iterate over workflows and print their run history:

#!/usr/bin/env bash
set -euo pipefail

for id in $(sophon workflows list --json | jq -r '.[].id'); do
  echo "== $id =="
  sophon workflows history "$id" --json | jq -r '.[] | "\(.status)\t\(.startedAt)"'
done

Trigger a workflow on demand and surface the execution ID:

sophon workflows execute "$WORKFLOW_ID"

Where to go next

• Command Reference — every command, subcommand, and flag
• Configuration & Auth — config file, env overrides, and tokens
• Workflows — build the automations you drive from here