Quickstart

Install the CLI, create a test, run it against your live app, and read exactly what broke — with your coding agent or from the terminal.

Install once; then either let your coding agent drive the CLI or type the commands yourself.

Prepend --dry-run to any command to try it offline with no API key. The CLI prints a canned sample in the real response shape.

Install and set up

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

Run it from your repo root. setup prompts for your API key (mint one in the Portal, in the workspace you want to test in), verifies it, stores it in ~/.testsprite/credentials, and installs the TestSprite agent skills into the project. Replace AGENT with claude, codex, cursor, cline, windsurf, antigravity, kiro or copilot; it takes a single target. Without --agent, setup installs for every agent it detects in the project, or claude if none. Run it once per project, and confirm what landed with testsprite agent status.

For CI or other non-interactive environments:

TESTSPRITE_API_KEY=$KEY testsprite setup --from-env --yes --agent AGENT

With a coding agent

The two installed skills mean you describe behavior and ask for a verdict; the agent runs the CLI.

Skill	Used when
testsprite-onboard	The repo has no tests yet: the agent reads your code, creates a project, writes about 8–15 tests, and smoke-runs only the 2–3 most important. It never runs the full suite on its own, because that costs credits.
testsprite-verify	Any feature or fix is about to be reported done: the agent reruns or authors a covering test, runs it to a verdict, and pulls the failure bundle on failure.

Prompts to start with:

Set up TestSprite for this repo and seed a starter test suite,
then smoke-run the most important flow.

Verify this change with TestSprite before you call it done.

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

Asking for a verdict (“run it to a verdict”) tells the agent a plan that was never run does not count. The agent shows you the drafted plan before creating it, ends every change with a verdict line (passed, failed, blocked or inconclusive) and a dashboard link, and says so explicitly when it could not run a test.

To keep the agent on track:

• Pin the project. The verify skill (not the CLI) resolves the project from TESTSPRITE_PROJECT_ID, then projectId in .testsprite/config.json, then a name match in testsprite project list, then asks you. Commit the pin to remove ambiguity: { "projectId": "proj_8f0f6" }.
• Keep credentials in place. The skills check testsprite auth status and stop if the CLI is missing or unauthenticated; they never install software or set keys. Re-run setup if they report it.
• Know the cost. Reruns of unchanged tests are billed like a fresh run; see Rerun & Auto-Heal.
• Check skill health. After upgrading the CLI, testsprite agent status flags stale or hand-modified skill files and exits 1 when any need attention. See Coding Agent Integration.
• Silence the nudge. Set TESTSPRITE_NO_SKILL_WARNING=1 if you drive the CLI by hand in a repo without the skill.

The steps below show what the agent runs.

From the terminal

Follow the steps below yourself.

Find or create a 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

For a deployed frontend app:

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

For an app running on your machine, use --local 3000 instead of --url (shorthand for --url http://localhost:3000). If your account is not yet on the V3 platform, the CLI refuses it with exit 7 and reason local-origin-requires-v3; use --url with a public URL, or create the project in the Portal. Runs against a local address open a tunnel automatically; see Environments.

To test another deployment, add a named environment and select it with --env <name>; omit --env for the Default.

Create and run a test

Write a plan file (JSON with projectId, type, name and a planSteps[] array) describing the behavior to verify. --run --wait triggers a real cloud run in a real browser and blocks until the verdict:

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

Exit 0 means passed; 1 means failed or blocked (see Exit codes). The --output json shape is a stable contract; when projectId and testId are known it includes a dashboardUrl for human review. See Output & Scripting.

When it fails, get the bundle

testsprite test failure summary test_3a9f21c7

testId              test_3a9f21c7
status              failed
failureKind         assertion
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 bundle:

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

It holds the failing step and its neighbors, DOM snapshots as text, the test source, the root-cause hypothesis and the recommended fix target, all from one snapshotId.

test failure get always returns the latest failure. To pin a specific run, use testsprite test artifact get <run-id>. The bundle needs saved test code, so a test that has never passed, or has only run through a tunnel, returns exit 4 with reason no_code; read testsprite test steps <test-id> and the summary instead.

Fix and rerun

testsprite test rerun test_3a9f21c7 --wait

A passing rerun is banked into your suite, so the next change reruns rather than recreates. Frontend reruns auto-heal by default; add --no-auto-heal to replay the saved script exactly. See Rerun & Auto-Heal.

Where to go next

Coding Agent Integration

Agent targets, install flags and skill health

The Agent Loop

Why create, run, read, fix, rerun compounds coverage

Creating Tests

Plan files, code files and batch create

Command Reference

Every command, flag and exit code