> ## Documentation Index
> Fetch the complete documentation index at: https://docs.testsprite.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart
> Create a test, run it against your live app, and read exactly what broke — in about 10 minutes.
By the end of this guide you'll have created a test, run it against your live app, and read exactly what broke — no code on your side.
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 — useful for learning the structure before you have credentials.
## Step 1: Install and sign in
Install the CLI globally and run the one-shot onboarding:
```bash theme={null}
npm install -g @testsprite/testsprite-cli
testsprite setup
```
`testsprite setup` prompts for your API key, verifies it, and installs the TestSprite verification skill into your agent's project configuration. Run it once per project.
For CI or non-interactive environments:
```bash theme={null}
TESTSPRITE_API_KEY=$TS_KEY testsprite setup --from-env --yes
```
## Step 2: Find your project
List the projects already on your account:
```bash theme={null}
testsprite project list
```
```text theme={null}
ID NAME TYPE FROM CREATED
proj_8f0f6... Checkout App frontend portal 2026-05-01
proj_2c4a1... Orders API backend cli 2026-05-10
```
If you need to create a new frontend project, pass the target URL:
```bash theme={null}
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](/mcp/getting-started/introduction), which owns the tunnel that exposes your local app to the cloud runner.
## Step 3: Create and run a test
Supply a plan file that describes the behavior to verify. The `--plan-from` flag accepts a JSON file with `projectId`, `type`, `name`, and a `planSteps[]` array. Then `--run --wait` triggers a real cloud run and blocks until the verdict:
```bash theme={null}
testsprite test create \
--project proj_8f0f6 \
--type frontend \
--plan-from ./checkout-flow.plan.json \
--run --wait \
--output json
```
The CLI runs the test against your live app using a real browser — not mocks — and returns a structured result:
```text theme={null}
exit 0 → test passed
exit 1 → test failed or blocked
```
Your agent or CI pipeline branches on the exit code. The `--output json` shape is a stable contract you can parse.
Use `--output json > result.json` to capture the full result for downstream processing. The JSON includes a `dashboardUrl` field on completion that deep-links into the Portal for the human review.
## Step 4: When it fails, get the bundle
First, get a one-screen triage card to orient yourself:
```bash theme={null}
testsprite test failure summary test_3a9f21c7
```
```text theme={null}
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:
```bash theme={null}
testsprite test failure get test_3a9f21c7 --out ./.testsprite/failure
```
The bundle is self-contained: failing step and its neighbors, DOM snapshots rendered as text your agent can read, the test source, the root-cause hypothesis, and the recommended fix target — all sharing one `snapshotId`. Your agent reads the bundle and has everything it needs to fix the code without another round trip.
`test failure get` always fetches the **latest** failure for the test. If multiple runs are in flight at once, use `testsprite test artifact get ` to pin the bundle to a specific run by its `runId`.
## Step 5: Fix and rerun
After editing the code, replay the test cheaply. Frontend reruns replay the saved script — no credits charged for a verbatim pass:
```bash theme={null}
testsprite test rerun test_3a9f21c7 --wait
```
```text theme={null}
runId run_5c1d...
status passed
startedAt 2026-06-15T10:22:14Z
finishedAt 2026-06-15T10:23:01Z
Dashboard: https://www.testsprite.com/dashboard/tests/proj_8f0f6/test/test_3a9f21c7
```
Exit 0. The test is banked into the durable suite. The next time your agent ships a change, it reruns rather than recreates — coverage compounds into a lasting record of every requirement it has ever gotten right.
**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](/cli/core/rerun-and-auto-heal#auto-heal).
## Step 6: Let your agent drive it
Install the TestSprite verification skill into your agent's project. `testsprite setup` already did this, but you can re-run the agent install step standalone for any target:
```bash theme={null}
testsprite agent install --target claude
```
```text theme={null}
.claude/skills/testsprite-verify/SKILL.md → written
```
The skill tells your agent when to run tests (after shipping a feature or fix), how to read the failure bundle, and how to loop until the test passes. From this point forward, your agent drives the create → run → failure get → fix → rerun loop without any human in the middle.
All five supported agent targets (claude, cursor, cline, antigravity, codex) and how the skill works
## Where to Go Next
Plan files, code files, batch create, and dependency authoring
Run, wait, run --all wave batches, and the credits model
All five agent targets and how the skill loop works
Every command, flag, and exit code in one place