CLI

Run testsbot test runs from your terminal or CI with @testsbot/cli.

Install

# One-off via npx
npx @testsbot/cli --help

# Or install globally
npm i -g @testsbot/cli
qa-clone --help

The package ships a single qa-clone binary (Node.js 22+).

Authenticate

Create an API key in the app under Settings → API keys (settings/api-keys) — keys start with tb_live_ and are shown exactly once. Store the key locally; subsequent commands pick it up automatically:

# Save your API key to ~/.qa-clone/config.json
npx @testsbot/cli auth --token tb_live_<your-key>

auth --token writes the key to ~/.qa-clone/config.json. Every later command re-reads it from there on each request and sends it as a bearer token, so you do not need to pass it again.

By default the CLI talks to https://api.testsbot.com. To target a different API (for example a local dev stack), set QA_CLONE_API_URL:

QA_CLONE_API_URL=http://localhost:3001 npx @testsbot/cli projects list

Commands

# List the projects you can access
npx @testsbot/cli projects list

# Trigger a run for a test case (prints the new run id)
npx @testsbot/cli runs trigger --test-case <test-case-id>

# Poll a run until it finishes (prints each status change)
npx @testsbot/cli runs follow <run-id>

# Tune the polling loop: every 10s, give up after 20 minutes
npx @testsbot/cli runs follow <run-id> --interval 10 --timeout 1200

Command	Description
auth	Store your API key for subsequent commands
projects list	List the projects you can access
runs trigger	Trigger a run for a test case
runs follow	Poll a run until it reaches a terminal status

runs follow exit codes (CI)

runs follow polls GET /runs/:id until the run reaches a terminal status (passed, failed, error, cancelled, skipped) or the timeout expires, printing a line on every status change. The exit code makes it gate-able in CI:

Exit code	Meaning
0	Run passed
1	Run finished but did not pass (failed, …)
2	Timeout — the run did not finish in time

Options: --interval <s> (polling interval, default 5) and --timeout <s> (overall deadline, default 600).

# Fail the CI job when the run does not pass
npx @testsbot/cli runs trigger --test-case tc_checkout
npx @testsbot/cli runs follow run_abc123 --timeout 900

JSON output

Pass the global --json flag (before the subcommand) to get the raw API response envelope { "ok": …, "data": … } on stdout — one parseable JSON line, no formatting:

npx @testsbot/cli --json projects list
# {"ok":true,"data":[{"id":"p1","name":"Acme"}]}

npx @testsbot/cli --json runs trigger --test-case tc_1
# {"ok":true,"data":{"runId":"run_abc123","status":"queued"}}

# `runs follow --json` suppresses status lines and prints the final run object
npx @testsbot/cli --json runs follow run_abc123 | jq -r '.data.status'
# passed

On a follow timeout the envelope is { "ok": false, "error": …, "data": <last run> } and the exit code is 2.

note

The CLI is a thin wrapper over the API. See the Quickstart to set up your first project.