sand CLI Reference

Fully generated documentation. Do not hand-edit this file outside the Documentation Refresh Workflow. Regenerate it with scripts/generate-cli-reference.sh so usage stays aligned with actual sand help output.

This reference captures the v1 Control Surface for managing Sandbox VMs, Allowed Folders, Sandbox Sessions, and generic Workload Commands.

Generation source

• Docs input hash: 4611688f2471ede3a9c27aa0340797287c49354225e6bbf68a7472d6629486cd
• Generator: scripts/generate-cli-reference.sh
• Help source command: swift run --package-path <repo> sand
• Usage sections below are captured from actual sand --help, sand <command> --help, sand <name> --help, and sand --version output.

Supported v1 command surface

• Global: sand --help, sand --version
• Top-level commands: doctor, create, list, apply, delete, folders
• Sandbox-first actions: sand <name> status, start, stop, shell, run <command> [args...], logs, spec

Current v1 boundaries

The v1 command surface is intentionally explicit and small:

• To clear a Sandbox VM completely, delete it and create a new one.
• To run Pi, use the same command shape as any other tool: sand <name> run pi [args...].
• Network access is outbound-only from the Sandbox VM in v1; inbound browser/server callbacks need a handoff flow outside the command surface.
• Commands name the target Sandbox VM explicitly, so it is always clear which environment you are operating.

sand --version

sand 0.1.0-dev

sand --help

Usage: sand <command> [options]

Commands:
  doctor                         Verify host prerequisites
  create <name> [options]        Create a Sandbox VM
  list                           List Sandbox VMs
  apply <name>                   Apply spec changes
  delete <name> [--force]        Delete a Sandbox VM
  folders <action> ...           Manage allowed Host Mac folders
  <name> status                  Show Sandbox VM status
  <name> start                   Start a Sandbox VM
  <name> stop                    Stop a Sandbox VM
  <name> shell                   Open a shell
  <name> run <command> [args...] Run a Workload Command
  <name> logs                    Show logs
  <name> spec                    Print the sandbox spec

Use `sand <command> --help` or `sand <name> --help` for command help.

sand doctor

Usage: sand doctor

Verifies host support, backend readiness, default image availability, and ~/.sand writability.

sand create

Usage: sand create <name> [--image <image>] [--cpus <count>] [--memory <size>] [--from <spec.yaml>]

Creates a Sandbox VM from generated defaults or from an authored spec.

sand list

Usage: sand list

Lists known Sandbox VMs with runtime state, image, and allowed folder count.

sand apply

Usage: sand apply <name>

Applies allowed spec changes to an existing Sandbox VM.

sand delete

Usage: sand delete <name> [--force]

Deletes the Sandbox VM runtime, guest state volume, and host metadata spec.

sand folders

Usage: sand folders <action> ...

Actions:
  folders add <name> <host-path> <rw|ro> [--as <guest-path>]
  folders list <name>
  folders remove <name> <host-path>

Sandbox-first actions

Use sand <name> --help to print the supported Sandbox Session and lifecycle actions for a named Sandbox VM.

Usage: sand <name> <action> [arguments]

Actions:
  status                         Show status
  start                          Start the Sandbox VM
  stop                           Stop the Sandbox VM
  shell                          Open an interactive shell
  run <command> [args...]        Run a Workload Command
  logs                           Show logs
  spec                           Print the sandbox spec