CLI reference (all grain commands)

Global flags:

Local default: unix socket. Remote example:

export GRAIN_API=http://127.0.0.1:7474   # after ssh -L …
export GRAIN_TOKEN=…
grain ls
grain --api http://sandbox:7474 ls

See Remote lab for the host + laptop workflow, and Remote sandbox host for firewall and systemd.

Daemon

grain update

Upgrades the CLI and Grain Desktop via the public install script (bash -s -- --desktop). Desktop is skipped gracefully when no release asset or GUI deps are available.

Most other commands may print a one-line stderr note when a newer release is known (cached for 24h). Disable notices with check_updates: false in config, GRAIN_CHECK_UPDATES=0, or GRAIN_NO_UPDATE_CHECK=1.

Images

VMs

grain new flags

Create path notes

• Cold boot (grain new without --from / --from-pool): host work is ~hundreds of ms; remaining time is guest UEFI/kernel/agent (~seconds on grain-ubuntu). Daemon logs create timing (image/disk/seed/start/wait ms).
• Agent-ready images use a minimal cloud-init seed; disk growpart is deferred after agent when the clone disk is larger than the base image.
• --from / --from-pool skip a full cold boot when the template was grain suspend’d with a qcow2 snapshot. Guide: lifecycle — fast create.

Warm pool (grain pool)

Pre-clone suspended (or optionally running) template VMs for fast claim. Config:

warm_pool:
  template: golden   # persistent stopped/suspended VM name
  size: 2            # ready members to keep (0 disables; max 32)
  running: false     # true = keep members agent-ready (uses host RAM)

grain new -i grain-ubuntu -n golden -p --wait agent
grain suspend golden
# set warm_pool in config, then:
grain pool fill
grain new --from-pool -n work1
grain pool status

Desktop: Settings → Warm pool and More → Promote to golden + fill pool. See Desktop and config.

grain recipe

Guide: Sandbox recipes.

Name is optional for sh / rm / x / fs / etc. when exactly one VM exists.

sh / x / cp path selection

grain cp (both directions)

# host → guest
grain cp ./script.sh lab:/tmp/script.sh
grain cp ~/proj lab:/work/proj/

# guest → host (reverse copy — same command, swap args)
grain cp lab:/work/proj/out.json ./out.json
grain cp lab:/var/log/cloud-init.log ./cloud-init.log

Remote CLI (GRAIN_API) uses the daemon’s agent proxy for cp — no scp from the laptop. Guest↔guest in one step is not supported (pull then push). Directory copies include hidden entries such as .git.

grain sync push | pull

Incremental directory sync with a host-side baseline under ~/.grain/sync/ (or data_dir/sync/). Requires the guest agent (no scp fallback). Directory roots only — use cp for single files. Regular symlinks are transferred as links (target string; not followed); directory symlinks are not descended. Hidden directories (including .git) are transferred so a git working tree stays a repository in the guest.

grain sync push  ~/proj  lab:/work/proj
grain sync pull  lab:/work/proj  ~/proj
grain sync push  ~/proj  lab:/work/proj --dry-run
grain sync pull  lab:/work/proj  ~/proj --delete --force

Exit codes: 0 ok, 1 usage, 2 conflicts (zero applies), 3 apply error. Dest-ahead paths are kept unless --force — successful sync is not always a full mirror.

MCP: grain_sync_push / grain_sync_pull with the same semantics.

GitHub Actions (grain act)

Runs nektos/act inside an ephemeral sandbox (Docker + act preset). Put act flags after --.

grain act -- -l
grain act -- -j test
grain act --keep -- -W .github/workflows/ci.yml

Full guide: Recipe: GitHub Actions (act).

Secrets & proxy

Profiles

grain profile ls
grain new --profile agent