Quickstart

Two ways to use the CLI

Both start with the same one-minute install.

With your coding agent. Most users let their coding agent — Claude Code, Codex, Cursor, Cline, Windsurf, Copilot — drive the CLI: you describe what you want in plain language, and the agent creates tests, triggers real cloud runs, reads what broke, fixes the code, and reruns. From the terminal. Prefer typing commands yourself? Every command the agent runs is one you can run directly — switch to the terminal tab in Step 2.

Step 1: Install and run setup

npm install -g @testsprite/testsprite-cli
testsprite setup

Run it once from your repo root and paste your API key when prompted. You’re set when you see:

TestSprite initialized.

  profile:  default
  email:    you@example.com

API Keys

Create one in the Portal under Settings → API Keys

Step 2: Run your first test

With your coding agent
From the terminal

1. Install the skills for your agent

Every prompt below is powered by these skills, so take five seconds to install them for the agent you use.

The CLI ships two agent skills — the instruction manual your coding agent follows: when to run tests, how to read failure bundles, and how to loop until green. Run the command from the root of the repo you’re working on — that’s where your agent looks for them:

testsprite agent install --target claude

testsprite agent install --target codex

testsprite agent install --target cursor

testsprite agent install --target windsurf   # also: cline, antigravity, kiro, copilot

Coding Agent Integration

All supported agents and where each skill file lands

2. Say this to your agent

Open your coding agent in the repo and say:

Help me test this project with TestSprite CLI

That’s the whole prompt. The skills you just installed carry the mechanics — your agent will:

Read your codebase to find the most important user flows (instead of blindly crawling).
Ask you for your deployed app URL — and login credentials, if your flows need them.
Create a TestSprite project and author a test suite (~8–15 tests with concrete assertions).
Run the highest-value flows in the cloud, against your live app, with a real browser.
Report back with pass/fail verdicts and dashboard links — and quote the credit cost before running anything more.

Have the URL and credentials ready; it’s the only thing the agent can’t figure out from your code.The CLI tests deployed http(s):// URLs and rejects localhost. If your app only runs locally, use the MCP Server instead — it owns the tunnel that exposes your local app to the cloud runner.

3. Make it part of your workflow

This is where the CLI earns its keep: the testsprite-verify skill triggers every time your agent finishes a change — it finds or creates the covering test, runs it to a verdict, and won’t report “done” on an unverified change. Make it a standing instruction:

Verify every functional change with TestSprite CLI before you call it done

And when a run fails, hand the agent the loop:

The TestSprite run failed — pull the failure bundle, fix the code, and rerun until it passes

The agent reads the failure bundle (failing step, DOM snapshots, root-cause hypothesis), fixes the code, and reruns. Every confirmed pass is banked into your durable suite, so the next change reruns rather than recreates — coverage compounds.

4. Keep the agent on track

Pin the project. Commit .testsprite/config.json with { "projectId": "proj_8f0f6" } at the repo root so the agent never guesses which project to run against.
Costs stay your call. The agent smoke-runs a few tests, never the full suite — full-suite runs are always your explicit choice, with the credit cost quoted up front.
Honesty is by design. If the agent can’t run a test (no credentials, no reachable URL), it says “shipped but unverified because X” rather than pretending.

Coding Agent Integration

What the installed skills do in detail, all eight agent targets, and skill health checks

Prepend --dry-run to any command to try the surface offline with no API key. The CLI emits a canned sample matching the real response shape.

1. Find or create your project

testsprite project list

ID             NAME             TYPE       FROM      CREATED
proj_8f0f6...  Checkout App     frontend   portal    2026-05-01
proj_2c4a1...  Orders API       backend    cli       2026-05-10

To create a new frontend project, pass the target URL:

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

The CLI only supports public http:// or https:// URLs. For localhost targets, use the MCP Server, which owns the tunnel that exposes your local app to the cloud runner.

2. Create and run a test

Supply a plan file that describes the behavior to verify — a JSON file with projectId, type, name, and a planSteps[] array. Then --run --wait triggers a real cloud run and blocks until the verdict:

testsprite test create \
  --project proj_8f0f6 \
  --type frontend \
  --plan-from ./checkout-flow.plan.json \
  --run --wait \
  --output json

The test runs against your live app in a real browser — not mocks:

exit 0  →  test passed
exit 1  →  test failed or blocked

Your CI pipeline or script branches on the exit code. The --output json shape is a stable contract you can parse, and includes a dashboardUrl field that deep-links into the Portal for human review.

3. When it fails, get the bundle

Start with a one-screen triage card:

testsprite test failure summary test_3a9f21c7

testId              test_3a9f21c7
status              failed
failureKind         element_not_found
snapshotId          snap_9b2c...
rootCauseHypothesis The "Place Order" button selector changed after the recent redesign.
recommendedFixTarget checkout.tsx line 42 — button aria-label

Then download the full failure bundle — the failing step and its neighbors, DOM snapshots rendered as text, the test source, and a recommended fix target, all from the same run:

testsprite test failure get test_3a9f21c7 --out ./.testsprite/failure

test failure get always fetches the latest failure. If multiple runs are in flight, use testsprite test artifact get <run-id> to pin the bundle to a specific run.

4. Fix and rerun

After editing the code, replay the test:

testsprite test rerun test_3a9f21c7 --wait

runId      run_5c1d...
status     passed
Dashboard: https://www.testsprite.com/dashboard/tests/proj_8f0f6/test/test_3a9f21c7

Exit 0. The test is banked into the durable suite — the next change reruns rather than recreates, and coverage compounds.

Auto-heal is on by default and uses a small amount of credit only when it actually repairs a drifted step — see Rerun & Auto-Heal.

Where to Go Next

Coding Agent Integration

All eight agent targets, install flags, skill health checks, and what the skills teach your agent

The Agent Loop

Why the loop is designed this way — self-consistent bundles and compounding coverage

Creating Tests

Plan files, code files, batch create, and dependency authoring

Command Reference

Every command, flag, and exit code in one place

Getting Started

Core

Integrations

Reference

Troubleshooting

Two ways to use the CLI

Step 1: Install and run setup

API Keys

Step 2: Run your first test

1. Install the skills for your agent

Coding Agent Integration

2. Say this to your agent

3. Make it part of your workflow

4. Keep the agent on track

Coding Agent Integration

1. Find or create your project

2. Create and run a test

3. When it fails, get the bundle

4. Fix and rerun

Where to Go Next

Coding Agent Integration

The Agent Loop

Creating Tests

Command Reference

​Two ways to use the CLI

​Step 1: Install and run setup

API Keys

​Step 2: Run your first test

​1. Install the skills for your agent

Coding Agent Integration

​2. Say this to your agent

​3. Make it part of your workflow

​4. Keep the agent on track

Coding Agent Integration

​1. Find or create your project

​2. Create and run a test

​3. When it fails, get the bundle

​4. Fix and rerun

​Where to Go Next

Coding Agent Integration

The Agent Loop

Creating Tests

Command Reference

Two ways to use the CLI

Step 1: Install and run setup

Step 2: Run your first test

1. Install the skills for your agent

2. Say this to your agent

3. Make it part of your workflow

4. Keep the agent on track

1. Find or create your project

2. Create and run a test

3. When it fails, get the bundle

4. Fix and rerun

Where to Go Next