Exit codes

Contract for agents and CI scripts invoking sp.

Code	Name	Meaning
0	Success	Parsed JSON on stdout when --json
1	API_ERROR	Backend returned error or HTTP non-success
2	USAGE	Invalid flags, missing config file, missing required args
3	AUTH_REQUIRED	No token available in non-interactive mode

stderr with --json

On exit 1 or 2 or 3, stderr contains a JSON error object:

{
  "ok": false,
  "command": "app list",
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "Set SP_TOKEN or run sp auth login"
  }
}

Agent retry guidance

Code	Retry?
0	No
1	Sometimes — after fixing data or if transient 5xx
2	No — fix invocation
3	After refresh/login