Skip to main content
Testboxes are in early beta. The interface and behavior may change as we iterate.

​
blacksmith testbox warmup

Dispatches a testbox and returns an ID immediately. Required before any run command. 
Usage:
  blacksmith testbox warmup <workflow> [flags]

Flags:
      --idle-timeout int        Idle timeout in minutes (default 30)
      --job string              Job name within the workflow
      --ref string              Git ref to dispatch against (default: repo's default branch)
      --ssh-public-key string   SSH public key to install on the testbox
FlagDescription
--idle-timeoutMinutes of inactivity before the testbox is automatically stopped. Defaults to 30.
--jobSpecific job within the workflow to run. Useful when the workflow defines multiple jobs.
--refGit ref (branch, tag, SHA) to dispatch the workflow against. Defaults to the repo’s default branch.
--ssh-public-keyPath to an SSH public key to install on the testbox. When omitted, a keypair is auto-generated and cached at ~/.blacksmith/testboxes/{id}/.
The returned testbox ID is the handle for all subsequent commands. 
blacksmith testbox warmup blacksmith-testbox.yml
# → tbx_01jkz5b3t9n8qr4xvwy0g6m2h1

blacksmith testbox warmup blacksmith-testbox.yml --ref feature/auth --job test-backend
# → tbx_01jkz6a2m4p7rs5ywx0h8n3c4d

​
blacksmith testbox run

Syncs local changes and executes a command on the testbox. If the testbox is still hydrating, the command blocks until the testbox is ready. 
Usage:
  blacksmith testbox run --id <id> "<command>" [flags]

Flags:
      --debug                    Show detailed sync timing information
      --id string                Testbox ID from warmup
      --ssh-private-key string   Path to SSH private key (use when warmup was called with --ssh-public-key)
FlagDescription
--idTestbox ID returned by warmup. Required.
--debugPrints detailed rsync timing and transfer statistics.
--ssh-private-keyPath to the SSH private key. Only needed when warmup was called with --ssh-public-key.
File sync uses rsync --delete --checksum to mirror the local working tree to the testbox. Deleted files locally are also removed on the testbox, so it always matches your local state exactly. The command exits with the remote command’s exit code, so agents can check it directly for pass/fail. 
blacksmith testbox run --id tbx_01jkz5b3t9... "npm test"
blacksmith testbox run --id tbx_01jkz5b3t9... "go test ./pkg/api/... -run TestHandler -v"
blacksmith testbox run --id tbx_01jkz5b3t9... "cd backend && php artisan test --filter=HealthCheckTest"
blacksmith testbox run --id tbx_01jkz5b3t9... "python -m pytest tests/test_api.py -k test_auth"

​
blacksmith testbox status

Shows the current status of a testbox. Supports --wait to block until the testbox is ready. 
Usage:
  blacksmith testbox status [flags]

Flags:
      --id string             Testbox ID to look up
      --wait                  Block until the testbox is ready
      --wait-timeout string   Maximum time to wait (e.g., 5m, 10m, 1h) (default "5m")
FlagDescription
--idTestbox ID returned by warmup. Required.
--waitBlock until the testbox reaches ready status.
--wait-timeoutMaximum duration to wait before timing out. Defaults to 5m.
Testbox statuses progress through: queued → hydrating → ready → completed.

​
blacksmith testbox stop

Stops a running testbox and cancels the underlying GitHub Actions run. 
Usage:
  blacksmith testbox stop --id <id> [flags]

Flags:
      --id string   Testbox ID to stop

​
blacksmith testbox init

Interactive onboarding TUI. Sets up a testbox workflow and agent skill for the current repository. The init command:
  1. Scans the repo’s .github/workflows/ for workflow files
  2. Prompts the user to select a workflow and job that has the dependencies and services they need
  3. Uses AI to transform the workflow into a testbox-compatible version (strips test execution, keeps setup, adds testbox actions)
  4. Writes .github/workflows/blacksmith-testbox.yml and an agent skill file
  5. Optionally creates a PR
The generated workflow is a workflow_dispatch-only workflow containing only setup steps, no test execution. The generated skill file teaches agents how to use Testbox in this repository.

​
blacksmith auth login

Authenticates with Blacksmith. Opens a browser for the OAuth flow. Saves a token to ~/.blacksmith/credentials. Required once per machine.