JSON Output and Error Handling
Success responses
Section titled “Success responses”Commands write one final JSON document to stdout:
{"status":"success","data":{},"request_id":"req_abc123"}Generation commands promote useful fields such as local_path, outputs, model, and credits_used to the top level.
Errors
Section titled “Errors”{"error":"RATE_LIMITED","message":"rate limit exceeded","hint":"retry after 60s","request_id":"req_abc123"}Keep every diagnostic field returned by a failed invocation:
trace_idrequest_idtask_idupstream_request_idstage
Common jq patterns
Section titled “Common jq patterns”# Confirm successgthonragents status | jq -e '.status == "success"'
# Extract a generated filegthonragents image generate --prompt "..." --model <model-id> \ | jq -r '.local_path'
# Extract all music outputsgthonragents music generate --prompt "..." --model <model-id> \ | jq -r '.outputs[].local_path'
# Read action contentgthonragents actions image-read --file ./screen.png \ | jq -r '.content'
# Print an error message when presentgthonragents ... | jq -r '.message // empty'Stream contract
Section titled “Stream contract”Validated model invocations emit one invocation_started JSON event to stderr before the server request. Stdout remains one final document, making it safe to pipe into jq or redirect to a file.
Partial audio download failures
Section titled “Partial audio download failures”Audio generation can produce multiple artifacts. If provider generation succeeds but an individual local download fails, that output contains an error field. Inspect every outputs[] item instead of treating one missing local path as total provider failure.
