CLI Reference¶

The sandbox CLI is your primary authoring tool. Run any command from inside a sandbox directory — the CLI searches upward from your current directory to find sandbox.yaml.

Command overview¶

Command	What it does
`sandbox init`	Scaffold a new sandbox directory
`sandbox build`	Build VM disk images
`sandbox shell`	Start VMs and open an interactive shell
`sandbox setup`	Run `setup.sh`, then open a shell
`sandbox answer`	Run `setup.sh` + `answer.sh`, then open a shell
`sandbox score`	Run `setup.sh` + `answer.sh` + `score.sh`, then open a shell
`sandbox test`	Run the full lifecycle non-interactively and report results
`sandbox exec`	Run a single command in a running VM
`sandbox instructions`	Preview the candidate instructions with live reload
`sandbox validate`	Run static checks without building
`sandbox start`	Start VMs in the background
`sandbox stop`	Stop and delete running VMs

sandbox init¶

Scaffold a new sandbox directory.

sandbox init [itemname]

Without itemname, the interactive wizard runs. With itemname, a single-VM scaffold is created immediately.

Flag	Default	Description
`--type`	auto-detected	`exam` or `lab`. Detected from the git remote URL if omitted.

sandbox init                        # interactive wizard
sandbox init foobar                 # single-VM fast path
sandbox init --type exam foobar

sandbox build¶

Build VM disk images from build.sh and the base image.

sandbox build [PATH]

Flag	Default	Description
`--vms`	all	Comma-separated list of VM names to build.
`--no-refresh-images`	false	Skip the registry check and use the local cache.
`-q, --quiet`	false	Suppress image download progress output.

sandbox build
sandbox build --vms cp,worker
sandbox build --no-refresh-images

Base images are cached locally after the first pull. sandbox shell runs sandbox build automatically if images are not yet built.

sandbox shell¶

Start VMs and open an interactive shell. Builds images first if needed.

sandbox shell [PATH]

Flag	Default	Description
`--target`	first VM	VM to open the shell in.
`--vms`	all	VMs to start.
`--ux`	false	SSH as the configured user to replicate the candidate experience.

sandbox shell
sandbox shell --target worker
sandbox shell --vms cp,worker --target cp
sandbox shell --ux

sandbox setup / answer / score / test¶

These are the core of the authoring loop. Each runs lifecycle scripts in sequence before handing control to you.

Command	Runs	Then
`sandbox setup`	`setup.sh`	Opens a shell
`sandbox answer`	`setup.sh` + `answer.sh`	Opens a shell
`sandbox score`	`setup.sh` + `answer.sh` + `score.sh`	Opens a shell
`sandbox test`	`setup.sh` → score → `answer.sh` → score	Prints results, no shell

sandbox test is the acceptance test. It passes when scoring returns zero checks before the answer is applied, and full marks after.

All accept --target and --vms.

sandbox setup                       # verify the environment starts correctly
sandbox answer                      # verify your reference solution works
sandbox score                       # verify scoring sees the correct result
sandbox test                        # run the full lifecycle and report

sandbox exec¶

Run a single command in a running VM. The VM must be started first.

sandbox exec [PATH] -- COMMAND [ARGS...]

Flag	Default	Description
`--target`	first VM	VM to run the command in.

sandbox exec -- whoami
sandbox exec -- cat /etc/os-release
sandbox exec --target worker -- systemctl status kubelet

sandbox instructions¶

Start a local preview server for the candidate instructions with live reload.

sandbox instructions [PATH]

Flag	Default	Description
`-o, --open`	false	Open the browser automatically.
`-p, --port`	random	Port to serve on.

sandbox instructions
sandbox instructions -o
sandbox instructions -p 3000 -o

Uses the production instructions image, so the preview matches exactly what candidates see. Requires Docker.

sandbox validate¶

Run static checks on the sandbox without building images.

sandbox validate [PATH]

Checks:

sandbox.yaml schema
Each tool's targetHost references a known VM
Required scripts exist in each VM's scripts directory
score.sh ends with scoring::report
Instructions sourcePath resolves to a markdown file
dist/ contains no git-tracked files

sandbox validate
sandbox validate ./items/foobar

sandbox start / stop¶

Start or stop VMs without opening a shell.

sandbox start [PATH]
sandbox stop [PATH]

Both accept --vms to target specific VMs. Use these when you want VMs running in the background while you work, then run sandbox exec to interact with them.

sandbox start
sandbox exec -- tail -f /var/log/syslog
sandbox stop

sandbox cache¶

Manage locally cached base images.

sandbox cache ls       # list cached images and sizes
sandbox cache df       # show total disk usage
sandbox cache prune    # remove orphaned cache objects
sandbox cache rm <image-ref>

Cache location:

macOS: ~/Library/Caches/sandbox-cli/images/
Linux: ~/.cache/sandbox-cli/images/

sandbox update¶

Update the CLI to the latest release.

sandbox update
sandbox update --force    # reinstall even if already on latest

In Codespaces, the CLI is managed by devbox — sandbox update is a no-op. Use devbox to upgrade.