CI/CD and automation

Use the ScaleBox CLI in non-interactive scripts, cron jobs, and CI pipelines. This guide focuses on the parts that matter most for reliable automation: API-key auth, machine-readable output, pagination, and async lifecycle polling.

In scripts, prefer auth login --api-key, -o json or -o json-compact, explicit pagination flags, and --async plus polling for long-running sandbox operations.

Authenticate non-interactively

Browser login is fine for humans, but automation should use an API key. Keep secrets in environment variables provided by your CI system rather than hard-coding them in scripts.

export SCALEBOX_SERVER_URL="https://api.scalebox.dev"
export SCALEBOX_API_KEY="sk-your-api-key"

scalebox-cli auth login \
  --api-key "$SCALEBOX_API_KEY" \
  --server-url "$SCALEBOX_SERVER_URL"

Choose machine-readable output

For automation, avoid human-oriented table output. Use -o json for readable logs or -o json-compact for line-oriented processing. You can also set a shell-wide default with SCALEBOX_OUTPUT.

export SCALEBOX_OUTPUT=json-compact

scalebox-cli template list --page 1 --limit 10
scalebox-cli sandbox list --page 1 --limit 20

Handle pagination explicitly

High-traffic list commands such as template list and sandbox list support --page, --limit, --all, and --max-items. In automation, pick one mode deliberately:

• Use --page plus --limit when you want a bounded page.
• Use --all when you need the full result set across multiple requests.
• Add --max-items to cap runtime and output volume.

# One page for dashboard or audit jobs
scalebox-cli -o json template list --page 2 --limit 10

# Full traversal for nightly sync jobs
scalebox-cli -o json-compact sandbox list --all --max-items 200

Use async create and poll for status

For long-running sandbox operations, prefer async mode and poll explicitly. This keeps your script logic simple and avoids assuming that a create, pause, or resume finishes immediately.

SANDBOX_ID="$(scalebox-cli -o json-compact sandbox create \
  --template tpl-abc123 \
  --name ci-job \
  --async | jq -r '.data.sandbox.id')"

until [ "$(scalebox-cli -o json-compact sandbox get "$SANDBOX_ID" | jq -r '.data.sandbox.status')" = "running" ]; do
  sleep 5
done

scalebox-cli sandbox exec "$SANDBOX_ID" -- echo "ready"

Practical script patterns

• Fail fast with set -euo pipefail in shell scripts.
• Prefer json-compact for piping into jq or other parsers.
• Use --no-terminal on sync sandbox create paths when a script should not open an interactive terminal.
• Check each command's --help because not every list command uses the same pagination flags.

See also

• Authentication
• Sandbox commands
• Template commands