CLI Reference

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

Flag	Description
`--idle-timeout`	Minutes of inactivity before the testbox is automatically stopped. Defaults to 30.
`--job`	Specific job within the workflow to run. Useful when the workflow defines multiple jobs.
`--ref`	Git ref (branch, tag, SHA) to dispatch the workflow against. Defaults to the repo’s default branch.
`--ssh-public-key`	Path 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)

Flag	Description
`--id`	Testbox ID returned by `warmup`. Required.
`--debug`	Prints detailed rsync timing and transfer statistics.
`--ssh-private-key`	Path 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")

Flag	Description
`--id`	Testbox ID returned by `warmup`. Required.
`--wait`	Block until the testbox reaches `ready` status.
`--wait-timeout`	Maximum 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:

Scans the repo’s .github/workflows/ for workflow files
Prompts the user to select a workflow and job that has the dependencies and services they need
Uses AI to transform the workflow into a testbox-compatible version (strips test execution, keeps setup, adds testbox actions)
Writes .github/workflows/blacksmith-testbox.yml and an agent skill file
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. Authenticates with Blacksmith. Opens a browser for the OAuth flow. Saves a token to ~/.blacksmith/credentials. Required once per machine.

Getting Started

Performance

Testboxes

Observability

Administration

FAQ

`blacksmith testbox warmup`

`blacksmith testbox run`

`blacksmith testbox status`

`blacksmith testbox stop`

`blacksmith testbox init`

​blacksmith testbox warmup

​blacksmith testbox run

​blacksmith testbox status

​blacksmith testbox stop

​blacksmith testbox init

​blacksmith auth login

`blacksmith testbox warmup`

`blacksmith testbox run`

`blacksmith testbox status`

`blacksmith testbox stop`

`blacksmith testbox init`

`blacksmith auth login`