Key Terms

Core CLI concepts — workspaces, API keys, projects, environments, tests, runs, statuses, credits, scopes, and failure bundles.

Workspace

Every project, test, and API key belongs to one workspace, and its runs draw on that workspace’s credits. One is created for you at signup, your default workspace, and you can create more or be invited into others. Each workspace has its own plan (Free or paid), members, roles, and credit balance; the default workspace can’t be deleted or transferred. The CLI has no “switch workspace” command: a key acts in the workspace it was minted in, and testsprite auth status shows which one. To work in several workspaces, keep one profile per workspace. See Workspaces.

Project

A project is the named container for your tests, identified by a stable projectId. It has a type (frontend or backend), its environments, and its tests.

The URL you give project create becomes the project’s Default environment: the app a frontend test opens, or the API base URL a backend test calls. A frontend project can use a loopback URL such as http://localhost:3000 (--url, or --local <port>); a backend project’s URL must be public.

testsprite project create --type frontend --name "Checkout App" --url https://app.example.com
testsprite project list

For local apps, see Test an app on your machine.

Environment

An environment is a named target inside a project: the URL to test plus what a run needs there, such as sign-in settings and custom variables. Every run selects one; without --env it uses the Default environment (project env list shows DEFAULT yes). A temporary environment is created for a --target-url or an unmatched --local port and removed when the run finishes; it does not count toward your environment limit. Free and Starter allow one environment per project, Standard 3, Pro and Enterprise unlimited. See Environments.

Test

A test lives in a project and is what the CLI runs, reruns, and reads results from. It has a stable testId, a type, a status, and a run history from every surface that ran it (see Run Source).

• Frontend: an ordered plan of browser steps (planSteps[]).
• Backend: executable code, typically Python, with optional variable dependencies (--produces / --needs).

testsprite test get test_3a9f21c7
testsprite test run test_3a9f21c7 --wait

Run and Run ID

A run is one execution of a test, from trigger to terminal verdict (passed, failed, blocked, or cancelled). test run and test rerun each start one and print its runId, which exists before the cloud engine starts; history marks reruns. A run keeps its own steps and artifacts (DOM snapshots as text, root-cause hypothesis, recommended fix target), and a later run never overwrites them.

testsprite test wait run_5c1d...          # resume waiting on an in-flight run
testsprite test artifact get run_5c1d...  # failure bundle pinned to this run

test failure get <test-id> always returns the latest failure, which can change if runs overlap.

Status

The normalized state of a test or run, shown in text mode and in --output json.

Value	Meaning	Terminal?
draft	No executable code yet	No
ready	Has code or a plan, never run	No
queued	Run accepted; engine not yet started	No
running	Execution in flight	No
passed	Latest completed run passed	Yes
failed	Latest completed run failed (including infrastructure crash)	Yes
blocked	Run rejected before a real verdict	Yes
cancelled	Run cancelled before a verdict	Yes
unknown	Status cannot be derived	—

Run status is the subset queued, running, passed, failed, blocked, cancelled. --wait stops at a terminal status: exit 0 for passed; exit 1 for failed, blocked, or cancelled (see Exit Codes).

Without --env, test list and test get show each test’s latest result in the project’s default environment, and --status filters on that. Pass --env <name> to read another environment.

testsprite test list --project proj_8f0f6 --status failed,blocked

Run Source

Every run is tagged with the surface that triggered it: cli (including reruns), portal, schedule, github_action, or mcp (projects created from MCP). Filter history with --source:

testsprite test result test_3a9f21c7 --history --source cli --since 7d

Credits

Credits are the unit of test execution. testsprite usage reports the balance of your active key’s workspace, and commands exit non-zero when the balance is insufficient (Exit Codes).

• A fresh test run charges credits. A test rerun is billed the same, whether or not auto-heal repairs anything. See Rerun & Auto-Heal.
• Backend runs consume credits per the workspace’s plan. The API does not expose the per-run cost, so check testsprite usage before a large batch.

API Key

The credential stored in ~/.testsprite/credentials and sent with every request. A key is minted in one workspace and tied to your membership there: what you create with it belongs to that workspace and draws on its balance, and it stops working if you leave or are removed. Keys need the Member role or above. Keys starting with sk-user- predate workspace keys and always act in your default workspace. testsprite auth status shows the identity, workspace, and scopes of the active key. See API Keys.

Scopes

Scopes are the permissions an API key carries. A key has every scope while you are a Member, Admin, or Owner of its workspace, and none as a Viewer. The CLI checks them before write and run requests and, when denied, prints the required scope and the ones your key holds. In short: test writes need write:tests, project and environment writes write:projects, schedule writes write:schedules, and starting, rerunning, or cancelling a run run:tests. Existing keys can use --local. See Authentication → Scopes for the full table.

Failure Bundle

A failure bundle is one run-scoped package for understanding a failure, assembled by the backend and downloaded in one command. It holds:

• the failing step and its ±1 neighbors
• DOM snapshots as text, each with a short description
• the test source (plan or code) at run time
• a root-cause hypothesis and a recommended fix target
• for backend tests: captured stdout (apiOutput) and the Python traceback (trace)

Every item shares one snapshotId; the CLI never mixes data from two runs.

mkdir -p .testsprite
testsprite test failure get test_3a9f21c7 --out ./.testsprite/failure
testsprite test failure summary test_3a9f21c7   # one-screen triage card

--failed-only trims the bundle to the failing step and its neighbors. See Reading Results for failure get vs artifact get.

Where to Go Next

The Agent Loop

The verification loop and where the CLI fits

Quickstart

Create a test, run it, and read the result

Reading Results

Statuses, failure bundles, run history

Command Reference

Every command and flag