Automation

Output contract

Authenticate using a runtime-injected KITTA_API_KEY. Never echo the key. stdout contains JSON results; stderr contains progress and JSON errors. --json forces compact JSON in an interactive terminal. It does not accept a JSON request body.

Capture results and failures

Bash:

if kitta audio voices list --all --json > voices.json 2> voices.log; then
  printf '%s\n' 'Voice list completed'
else
  result=$?
  printf 'Command failed with exit %s\n' "$result" >&2
  exit "$result"
fi

PowerShell:

kitta audio voices list --all --json 1> voices.json 2> voices.log
$result = $LASTEXITCODE
if ($result -ne 0) { throw "Kitta failed with exit $result; inspect voices.log and partial output." }
$voices = Get-Content -Raw voices.json | ConvertFrom-Json

Protect result and diagnostic files as customer data. A nonzero result may still contain useful partial output.

Exit codes

Pagination

--all follows pages; --max-pages defaults to 100. At the limit, stdout contains complete: false and nextPage, and the command exits 5. Do not treat this as a complete inventory. Voice language filtering runs on fetched records; without --all it covers only the current page.

Retry policy

Do not wrap every command in an unconditional retry loop. For paid TTS, persist a business idempotency key and keep input unchanged. Other paid operations do not automatically retry and may have unknown outcomes after disconnects.

Next: task recovery.