Driving Spaceboy from a coding agent

The contract

• Always pass --json; stdout is exactly one JSON value, and progress diagnostics stream on stderr.
• Check exit codes before parsing: 3 means re-authenticate, 4 means the plan or role does not allow the action (surface the upgrade path to the human).
• Every mutation is idempotent server-side; re-running a failed command is safe.
• Long operations (agent message, deploy, session start) poll internally and block until a terminal state — no busy-waiting needed on your side.

A typical build loop

export SPACEBOY_API_KEY=rbk_...
PROJECT=$(repobot --json projects create --name "todo-app" | jq -r .id)
repobot --json agent message "Build a todo list with auth" --project "$PROJECT"
repobot --json deploy --project "$PROJECT" --target production | jq -r .resultUrl

If agent message times out, the run keeps going server-side; resume with spaceboy agent tail (it defaults to the project's latest conversation, or pass --conversation <id>).