CLI reference

# Option 1: one-line script (installs to $HOME/.local/bin/boxlite, with an embedded runtime)
# Note: environment variables must be placed on the sh side of the pipe; placing them before curl does not pass them to the installer
curl -fsSL https://sh.boxlite.ai | sh
# Option 2: compile and install from crates.io
cargo install boxlite-cli
# Option 3: install a prebuilt binary via cargo-binstall
cargo binstall boxlite-cli
# Verify the installation
boxlite --version
boxlite --help

# 1) Run a command in an alpine sandbox; auto-clean after the command finishes (--rm)
boxlite run --rm alpine:latest echo "hello from boxlite"

# 2) Create a named, persistent sandbox in the background for later exec
boxlite run -d --name mybox alpine:latest sleep 3600

# 3) Run a command in the persistent sandbox
boxlite exec mybox -- echo "running inside mybox"

# 4) List running sandboxes
boxlite list

# 5) Remove when done (-f forcibly removes a running sandbox)
boxlite rm -f mybox

boxlite [GLOBAL OPTIONS] <COMMAND> [ARGS...]

boxlite run [OPTIONS] <IMAGE> [COMMAND...]

# Interactive shell (allocate a TTY)
boxlite run -it --rm alpine:latest sh

# Limit resources + mount a volume (read-only) + forward a port + set an environment variable
boxlite run --rm \
  --cpus 2 --memory 1024 \
  -v "$(pwd)/data:/data:ro" \
  -p 8080:80 \
  -e MY_VAR=hello \
  nginx:latest

boxlite exec [OPTIONS] <BOX> -- <COMMAND...>

# Run a command in the sandbox named mybox
boxlite exec mybox -- ls -la /

# Enter the sandbox interactively (requires a TTY terminal)
boxlite exec -it mybox -- sh

boxlite create [OPTIONS] <IMAGE>

BOX_ID=$(boxlite create --name worker alpine:latest)
echo "created: $BOX_ID"
boxlite start worker
boxlite exec worker -- uname -a

boxlite list                  # running sandboxes (table)
boxlite ls -a --format json   # all sandboxes, JSON output
boxlite ps -q                 # print IDs only

boxlite rm mybox              # remove one
boxlite rm -f box1 box2       # forcibly remove multiple
boxlite rm --all -f           # remove all and skip confirmation

boxlite start <TARGETS...>
boxlite stop  <TARGETS...>
boxlite restart <TARGETS...>

boxlite stop mybox
boxlite start mybox
boxlite restart box1 box2

boxlite pull alpine:latest
boxlite pull -q python:slim

boxlite images
boxlite images --format json

boxlite inspect mybox
boxlite inspect --latest --format yaml
boxlite inspect mybox -f '{{.State.Status}}'

# host -> sandbox
boxlite cp ./app.tar mybox:/tmp/app.tar

# sandbox -> host
boxlite cp mybox:/var/log/app.log ./app.log

boxlite info
boxlite info --format json

boxlite logs mybox
boxlite logs -n 100 -f mybox

boxlite stats mybox
boxlite stats --format json mybox
boxlite stats -s mybox

# Start a local service with zero config (permissive mode, accepts any/no bearer)
boxlite serve

# Specify a port and require an API key
boxlite serve --port 9000 --api-key "<YOUR_API_KEY>"  # replace with your key

# Log in with an API key (key passed via stdin, kept out of shell history)
printf '%s' "<YOUR_API_KEY>" | boxlite auth login --url https://api.boxlite.ai --api-key-stdin

# Check status / identity
boxlite auth status
boxlite auth whoami

# Log out
boxlite auth logout

boxlite completion <bash|zsh|fish>

# zsh example
boxlite completion zsh > "${fpath[1]}/_boxlite"

# bash example
boxlite completion bash > /etc/bash_completion.d/boxlite

-v hostPath:boxPath[:ro|rw]   # bind mount
-v boxPath[:ro]               # anonymous volume (host-side directory allocated automatically)

boxlite run --rm -v "$(pwd):/work:ro" alpine:latest ls /work   # read-only
boxlite run --rm -v /data:/app/data alpine:latest sh           # read-write (default)
boxlite run --rm -v /cache:ro alpine:latest sh                 # anonymous read-only volume

-p [hostPort:]boxPort[/tcp|udp]

{
  "image_registries": [
    {
      "host": "ghcr.io",
      "search": true
    },
    {
      "host": "docker.io",
      "search": true
    },
    {
      "host": "registry.local:5000",
      "transport": "http",
      "search": true
    },
    {
      "host": "registry.example.com",
      "transport": "https",
      "skip_verify": true,
      "auth": {
        "type": "basic",
        "username": "user",
        "password": "<YOUR_REGISTRY_PASSWORD>"
      }
    }
  ]
}

if boxlite run --rm alpine:latest sh -c 'exit 3'; then
  echo "ok"
else
  echo "command failed with exit code $?"   # 3
fi