CLI reference

The test-scale CLI is a thin client over the control plane REST API. It is ideal for terminals, CI, and make docker-run wrappers.

Install the CLI

From the repository:

make build
./bin/test-scale --help

Globally:

go install ./cmd/cli
export PATH="$PATH:$(go env GOPATH)/bin"

Homebrew: brew install MohamedBenTaher/tap/test-scale

Environment variables

Variable	Default	Purpose
`CONTROL_PLANE_URL`	`http://localhost:8080`	Base URL for API and UI
`PROMETHEUS_URL`	`http://localhost:9090`	Live metrics during watch mode
`TEST_SCALE_API_KEY`	none	Sent as `X-Test-Scale-Key` when set

Docker Compose: make docker-run sources deploy/docker/scripts/ports.sh, which sets URL, ports, and the local dev API key.

Commands

`submit` / `run` — start a run

test-scale submit -f plan.yaml
test-scale run -f plan.yaml

Flag	Description
`-f`, `--file`	Plan YAML path (required)
`--watch`	Stream live progress (default on TTY)
`--no-watch`	Submit and exit
`--json`	Machine-readable output; disables watch

Watch mode prints a live dashboard to stderr (status, workers, RPS, p95, progress). stdout receives a short summary when the run completes.

Plan files support ${ENV_VAR} expansion at parse time — export secrets before run.

`status` / `watch` — inspect a run

test-scale status --run-id run-0708-0843-b2ab
test-scale watch -r run-0708-0843-b2ab

Accepts human slugs (run-0708-0843-b2ab) or UUIDs.

`plans` / `ls` — list saved plans

test-scale plans

Returns JSON array of persisted plans.

`rerun` / `retry` — run a saved plan again

test-scale rerun --plan-id <uuid>

Creates a new run with the same stored request definition — ideal for regression checks.

`compare` / `diff` — two-run comparison

test-scale compare --current run-a --baseline run-b
test-scale diff -c run-a -b run-b --fail-on-regression

--fail-on-regression exits non-zero when p95 regresses more than 20% vs baseline — useful in CI.

`open` / `ui` — web UI

test-scale open
test-scale open --print   # print URL only

Opens the embedded Web UI. Pings /ping first unless --check=false.

Flag	Description
`--print`	Print URL instead of opening browser
`--check`	Verify control plane is up (default: true)

Alias cheat sheet

Canonical	Aliases
`submit`	`run`, `start`, `up`
`status`	`watch`, `w`, `st`, `get`, `show`
`plans`	`ls`, `list`
`rerun`	`retry`, `again`
`compare`	`diff`, `cmp`
`open`	`ui`, `dashboard`, `web`

Workflows

Local Docker

make quickstart
make docker-run PLAN=examples/http-post.yaml
make docker-open

CI gate

test-scale run -f ci-smoke.yaml --json --no-watch
test-scale diff -c "$RUN" -b "$BASELINE" --fail-on-regression

Kubernetes (port-forward)

kubectl port-forward -n test-scale svc/test-scale-ctrl-plane 8080:8080 &
export CONTROL_PLANE_URL=http://localhost:8080
export TEST_SCALE_API_KEY=<from helm notes>
test-scale run -f deploy/kubernetes/ci-smoke.yaml

Troubleshooting

Issue	Fix
`command not found`	`./bin/test-scale` or add `~/go/bin` to PATH
`connection refused`	Start control plane (`make docker-up` or Helm)
`valid Test Scale API key is required`	Export `TEST_SCALE_API_KEY` or use `make docker-run`
Watch shows no metrics	Start Prometheus; set `PROMETHEUS_URL`
`invalid id`	Use slug or valid UUID

See First run troubleshooting.