> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blacksmith.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

> Testbox CLI commands and flags

<Note>Testboxes are in early beta. The interface and behavior may change as we iterate.</Note>

## `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.

```bash theme={"system"}
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.

```bash theme={"system"}
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:

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.