raft / docs
Guides

Script the CLI

You can call Raft from a Linux controller or trusted CI runner with Python 3.11.8+, OpenSSH and configured host access. Your SSH identity controls the host through sudo; do not expose it to untrusted code. For one-shot work, prefer raft run over writing your own allocation and cleanup logic.

Read output

Use raft --json COMMAND ... for JSON Lines events. Put --json before the command:

raft --json list --location lab | jq 'select(.type == "data") | .value'

Events have a type: data carries structured value; stdout and stderr carry base64 bytes in data with encoding: "base64"; error carries code and message; the final exit carries code. Decode stream chunks in order within each channel, not as independent text lines. ssh, forward and desktop reject JSON mode. Help and version need no host configuration.

Without global JSON mode, stdout is command-specific:

CommandOutput
new, fork, recoverOne qualified handle
exec --detachOne job ID
listJSONL with box, state, stopAt, deleteAt, disk, note; no records for no boxes
locations, capacity --json, pruneOne JSON object per location or candidate
info, usage, config, statusA JSON object; info uses native Incus keys
logsRetained combined output
exec, runPayload stdout and stderr

stopAt and deleteAt are Unix seconds encoded as strings, or "" when absent. note is a note object or null; disk is "shared" or a size such as "20GiB". usage reports memoryBytes, memoryLimit, cpuTime, effectiveCpus, filesystemUsedBytes, filesystemAvailableBytes and filesystemScope. Shared filesystem counters describe the pool, not one box.

Keep stderr separate from parsed stdout. Recovery prints its allocated handle on stderr before import completes. Set RAFT_NO_UPDATE_CHECK=1 for pinned runs to suppress release notices; JSON mode also suppresses them.

Preserve failures

Successful control operations return 0; recognized operation/configuration errors return 1; argument errors return 2; self-update --check returns 100 when an update exists. Caught Ctrl+C returns 130. Synchronous exec preserves the command's status when transport succeeds, and reads caller stdin:

printf '%s\n' 'input from the controller' | raft exec "$box" -- cat
raft exec "$box" -- bash -lc 'echo "Command failed" >&2; exit 7'

SSH failures can report transport status instead. status returning zero only confirms the query; read the job's terminal state and exitCode for its result. See background jobs.

Wait before running setup

Creation returns before guest services are necessarily ready. This Bash example creates a task-owned persistent box with explicit settings and retries only a harmless readiness probe:

box=$(raft new --location lab --ttl 3600 --cpu 1 --memory 2GiB --disk shared --persistent --purpose "Scripted project setup" --owner "Local operator" --next "Inspect and stop after setup") || exit "$?"
ready=false
for attempt in {1..30}; do
  if raft exec "$box" -- true; then ready=true; break; fi
  sleep 2
done
if [ "$ready" != true ]; then
  printf 'Guest not ready; inspect %s\n' "$box" >&2
  exit 1
fi
raft exec "$box" -- node --version

The wait is about a minute plus transport time. If it fails, the box still exists: inspect it before stopping or destroying it. Probe Docker with docker info or an application with its health check separately; command readiness does not prove either is ready. After collecting results, stop your persistent box. Host retention may later delete it.

Pass explicit location, TTL, sizes and lifecycle flags when scripts need stable settings. Controller defaults otherwise differ. Supply all note fields if host policy requires them.

Recover from a lost connection

Raft does not automatically retry ordinary operations or provide idempotency keys. A dropped connection during create, resume, import or execution can leave the operation completed remotely. Inspect inventory, metadata and command effects before retrying. Creation can leave a saved box without delivering a handle to stdout.

Use the recovery handle printed on stderr for an interrupted import. Never treat an unreachable host as proof that a box is absent or a command did not run.

On this page