CLI commands¶

barista is a thin client over the Node Agent API. Direct-node commands address an instance id. Fleet commands address a stable session name in the coordination bucket.

Global flags¶

Flag	Environment	Default	Meaning
`--node <addr>`	`BARISTA_NODE`	`127.0.0.1:7070`	Node address: `host:port` or a Unix socket path.
`--json`		off	Machine-readable output. Use this in scripts.

Mutating commands subscribe to events before submitting, then wait for the operation to finish. Each invocation generates its own idempotency key. Contract A clients can supply and reuse a key directly; the CLI does not expose that key as a flag.

Direct-node lifecycle¶

`barista create`¶

Create an instance without starting it:

barista create \
  [--instance-id <ulid>] \
  --image ghcr.io/acme/agent:2026-08 \
  --digest sha256:9b2c0f… \
  [--vcpu 1] [--mem-mib 512] [--ttl-seconds 0] \
  [--egress mediated|mediated:http-https-only] \
  [--require-hardware-isolation] \
  -- <command>...

If --instance-id is omitted, the CLI generates a ULID and prints it in the result. The Node Agent requires a digest. You may also use the inline form --image ghcr.io/acme/agent@sha256:… and omit --digest.

The protobuf InstanceSpec supports more fields than this convenience command, including disk size, environment, readiness, hooks, labels, and TTL action. Use a generated API client when you need those fields; they are not CLI flags.

`barista start` / `barista stop`¶

barista start <instance-id>
barista stop <instance-id> [--grace-seconds 10]

Starting from STOPPED is a cold boot. Stop preserves disk and loses memory.

`barista pause` / `barista resume`¶

barista pause <instance-id> [--require-memory]
barista resume <instance-id> [--snapshot <snapshot-id>] [--require-memory]

Pause captures what the runtime supports and releases the sandbox. On fake, it is honestly DISK_ONLY; --require-memory refuses that downgrade. Resume uses the latest snapshot unless --snapshot names an explicit one.

`barista checkpoint`¶

barista checkpoint <instance-id>

Checkpoint promises a live capture. It fails with CAPABILITY_MISSING on the current runtimes because neither reports live_checkpoint.

`barista wake-at`¶

barista wake-at <instance-id> 5m
barista wake-at <instance-id> 2026-08-09T09:00:00Z
barista wake-at <instance-id> --clear

The time may be an RFC 3339 timestamp with Z or a numeric offset, or a relative 90s, 5m, 2h, or 3d duration. One alarm exists per instance; setting a new one replaces the previous alarm.

`barista destroy`¶

barista destroy <instance-id> [--keep-snapshots]

Working inside an instance¶

`barista exec`¶

barista exec <instance-id> -- <command>...
barista exec <instance-id> --tty=false -- <command>...

The command is required. A PTY is allocated automatically when stdin is a terminal unless --tty overrides it. The workload exit code becomes the CLI exit code.

`barista cp`¶

barista cp ./local.json <instance-id>:/app/config.json
barista cp <instance-id>:/app/out.log ./out.log

Exec and copy require a reachable guest agent.

Snapshots¶

barista snapshot create <instance-id> [--name <label>]
barista snapshot delete <snapshot-id>
barista snapshots [--instance <instance-id>]

create captures a retained snapshot on a memory-capable runtime. A running source may freeze briefly; the operation reports froze_workload. Snapshot identity is always the id; --name is a per-instance human label.

Inspection¶

barista ls
barista get <instance-id>
barista node info
barista doctor
barista events [--instance <instance-id>] [--from-cursor <n>]

node info reports capabilities without deciding whether they are sufficient. doctor is a strict deployment gate: it exits non-zero if the substrate, guest channel, journal, or memory-preserving pause capability is unavailable.

Fleet¶

Fleet commands talk to the bucket rather than a node. They require BARISTA_FLEET_BUCKET and ambient AWS credentials.

barista fleet apply <name> --image <image> --digest <sha256:…> \
  [--vcpu 1] [--mem-mib 512] [--ttl-seconds 0] \
  [--on-owner-loss coldboot|hold] -- <command>...
barista fleet ls
barista fleet resolve <name>

apply writes desired state; nodes compete to acquire it. No command chooses a node. resolve returns the current owner and advertised endpoint, or exits 1 when the name is unowned.

Exit codes¶

Code	Meaning
`0`	Success.
`1`	Generic failure or a reason without a dedicated code.
`3`	`CAPABILITY_MISSING`.
`4`	`CONCURRENT_OPERATION`.
`5`	`SUBSTRATE_UNAVAILABLE`; retry later.
`6`	`INVALID_SPEC` or `TEMPLATE_NOT_FOUND`; fix the request.

For barista exec, the workload's exit code is preserved.

JSON output¶

barista --json get <instance-id>
barista --json events --instance <instance-id>

Result commands emit JSON to stdout. Errors emit JSON to stderr. Streaming commands emit one object per event or frame.

CLI commands¶

Global flags¶

Direct-node lifecycle¶

barista create¶

barista start / barista stop¶

barista pause / barista resume¶

barista checkpoint¶

barista wake-at¶

barista destroy¶