Exit codes and JSON errors

The CLI uses stable exit codes so automation can branch without parsing human text.

Exit code	Error code	Meaning
0	n/a	Success
1	unexpected_error	Unhandled runtime failure
2	usage_error	Invalid arguments, invalid manifest, or missing required configuration
3	not_authenticated	Missing token or rejected CLI token
4	source_resolution_failed	Local file, directory, URL, or relative path resolution failed
5	api_error	The ChalkSurf API returned a non-authentication failure
6	wait_timed_out	Waiting ended before all jobs reached a terminal state
7	job_failed	One or more jobs completed with failure

These codes are mirrored in error.exitCode and error.code inside the JSON envelope.

Success envelope

{
  "schemaVersion": "v1",
  "command": "sheet import",
  "ok": true,
  "result": {},
  "warnings": []
}

Known failure envelope

{
  "schemaVersion": "v1",
  "command": "sheet import",
  "ok": false,
  "result": {},
  "error": {
    "code": "source_resolution_failed",
    "message": "The requested local source does not exist.",
    "exitCode": 4,
    "retryable": false
  },
  "warnings": []
}

API errors can additionally expose a stable error.agentErrorCode and structured error.agentErrorDetails. In JSON mode, standard error is reserved for unexpected runtime failures. Wait and import commands retain their result payload when ok is false.