> ## 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 for Coding Agents

> Let your coding agent take this repo from zero to its first real test run — install once, then talk to your agent instead of the terminal.

This page is for you if a coding agent — Claude Code, Codex, Cursor, Cline, Windsurf, Copilot — writes most of your code. You install the CLI once; from then on you describe what you want in plain language and **the agent drives the CLI**: it creates tests, triggers real cloud runs, reads the failure bundles, fixes the code, and reruns.

By the end of this page your agent will have set up TestSprite in your repo, created a first test, and run it against your live app to a pass/fail verdict — without you typing another `testsprite` command.

<Note>
  Prefer to type the commands yourself? The human-oriented [Quickstart](/cli/getting-started/quickstart) walks the same loop from the terminal.
</Note>

## Step 1: Install and run setup (the only terminal step)

```bash theme={null}
npm install -g @testsprite/testsprite-cli
testsprite setup
```

Run `testsprite setup` from your repo root. It chains three things:

1. Prompts for your API key (created in the Portal under <kbd>Settings → API Keys</kbd> — see [API Keys](/web-portal/admin/api-keys)) and verifies it against the platform.
2. Stores the key in `~/.testsprite/credentials`.
3. Installs the **TestSprite agent skills** into your agent's project configuration — for Claude Code that's `.claude/skills/testsprite-verify/SKILL.md` and `.claude/skills/testsprite-onboard/SKILL.md`.

Run it once per project. That's the entire manual surface — everything after this step happens through your agent.

<Tip>
  You can even delegate this step: paste the two commands above into your agent and let it run them. `setup` supports a fully non-interactive form (`TESTSPRITE_API_KEY=$KEY testsprite setup --from-env --yes`) for exactly this.
</Tip>

<Note>
  The skill install is **pure-local** — it only writes files inside your repo, makes no network requests, and needs no credentials. Eight agent targets are supported (`claude`, `codex`, `cline`, `antigravity`, `kiro`, `windsurf`, `copilot`, `cursor`); see [Coding Agent Integration](/cli/core/agent-integration#supported-agents) for where each skill file lands and how to install for multiple agents at once.
</Note>

## Step 2: The two skills your agent just learned

`testsprite setup` installed two skill files. They are the difference between an agent that *has* a CLI and an agent that *knows when and how to use it* — you never have to spell out the mechanics in a prompt.

| Skill                | Job                                                                                  | Your agent reaches for it when…                                                  |
| :------------------- | :----------------------------------------------------------------------------------- | :------------------------------------------------------------------------------- |
| `testsprite-onboard` | Take a repo with **no tests yet** to a seeded, runnable suite with a first green run | Right after setup, or when you say "set up tests", "bootstrap", "get me started" |
| `testsprite-verify`  | Verify **every code change** with a real test run before the agent reports it done   | A feature or fix lands and the agent is about to say "done"                      |

### `testsprite-onboard` — seed a suite in an empty project

**What it does.** The agent reads your codebase first — routes, handlers, the 4–8 most important user flows — instead of blindly crawling. It then creates a TestSprite project (frontend projects always get a target URL, plus login credentials if your flows need them), authors roughly 8–15 tests with concrete, observable assertions, batch-creates them, and **smoke-runs only the 2–3 highest-value happy paths**.

**What you should expect to see:**

* The agent asks for your deployed app URL (and login credentials, if needed) before creating a frontend project.
* A report like: *"Your project now has 12 tests covering login, checkout, search… I smoke-ran 3 — here are the results and dashboard links."*
* It will **not** auto-run the full suite — running everything costs credits, so it quotes the cost and leaves that choice to you.

### `testsprite-verify` — verify every change before "done"

**What it does.** After finishing a feature or fix, the agent preflights (`testsprite --version`, `testsprite auth status`), finds the right project, and picks the cheapest honest verification: rerun an existing test that covers the behavior, or author a new one (a plain-language plan file for frontend, a Python script for backend). It runs to a terminal verdict with `--wait`, and on failure pulls the failure bundle before deciding whether your change caused it.

**What you should expect to see:**

* The agent shows you the drafted plan or test code **before** creating it — one short confirmation, since creating writes to your project.
* Every shipped change ends with a verdict line: test id, name, and `passed` / `failed` / `blocked` / `inconclusive`, plus a dashboard link.
* On failure, a one-line root-cause hypothesis from the bundle — but the agent does **not** auto-fix on that hypothesis alone; it reads the evidence first.
* If it *can't* run a test (no credentials, no reachable URL, repo not linked), it says so explicitly — *"shipped but unverified because X"* — rather than pretending. That honesty is by design.

<Note>
  Both skills are versioned with the CLI. After upgrading, `testsprite agent status` tells you if an installed skill file is `stale` or was hand-`modified` — it exits `1` when anything needs attention, so it's CI-gateable. See [Checking skill health](/cli/core/agent-integration#checking-skill-health).
</Note>

## Step 3: What to say to your agent

You don't need to name commands or flags — the skills carry the mechanics. Describe the **behavior** you care about and ask for a **verdict**. Copy-paste starters:

**Your first test (right after setup):**

```text theme={null}
Set up TestSprite for this repo and seed a starter test suite,
then smoke-run the most important flow.
```

The agent onboards: creates the project, authors a suite from what it finds in your code, smoke-runs the top flows, and hands you dashboard links. You've gone from "installed" to "first real test run" in one prompt.

**Verify a change (the everyday prompt):**

```text theme={null}
Verify this change with TestSprite before you call it done.
```

The agent finds or creates the covering test, runs it against your deployed app, and reports the verdict.

**Target a specific behavior:**

```text theme={null}
Create a TestSprite test that covers the checkout happy path
and run it to a verdict.
```

**Drive the fix loop:**

```text theme={null}
The TestSprite run failed — pull the failure bundle, fix the code,
and rerun until it passes.
```

<Tip>
  The phrase **"run it to a verdict"** is the useful one: it tells the agent a drafted-but-never-run plan doesn't count. The verify skill already enforces this — at least one terminal verdict per shipped change — but saying it keeps expectations aligned.
</Tip>

## Step 4: The loop, end to end

Here's what a real session looks like once the skills are in place:

<Steps>
  <Step title="You ask for a feature">
    *"Add a coupon-code field to checkout, and verify it with TestSprite."* The agent writes the code and gets it deployed somewhere reachable (a preview or staging URL) — the cloud runner tests deployed apps, not your working tree.
  </Step>

  <Step title="The agent creates and runs a test">
    It drafts a plan describing the behavior in user-intent terms, shows it to you, then:

    ```bash theme={null}
    testsprite test create --project proj_8f0f6 --type frontend \
      --plan-from ./coupon-code.plan.json --run --wait --output json
    ```

    A real browser exercises your live app. Exit `0` = passed, `1` = failed.
  </Step>

  <Step title="On failure, it reads the bundle — not the tea leaves">
    ```bash theme={null}
    testsprite test artifact get run_5c1d... --out ./.testsprite/failure
    ```

    One self-consistent bundle: the failing step and neighbors, DOM snapshots rendered as text, the test source, a root-cause hypothesis, and a recommended fix target — all from the same run.
  </Step>

  <Step title="It fixes and reruns until green">
    ```bash theme={null}
    testsprite test rerun test_3a9f21c7 --wait
    ```

    Frontend reruns replay the saved script — free unless [auto-heal](/cli/core/rerun-and-auto-heal#auto-heal) repairs a drifted step. The confirmed pass is banked into your durable suite, so the next change **reruns** rather than recreates. Coverage compounds.
  </Step>
</Steps>

<Card title="The Agent Loop" href="/cli/concepts/the-agent-loop" icon="arrows-rotate" horizontal>
  Why the loop is designed this way — self-consistent bundles, compounding coverage, and the machine-readable contract underneath.
</Card>

## Step 5: Keep the agent on track

A few conventions make the agent-driven flow reliable:

**Pin the project.** The verify skill resolves which project to run against in priority order: the `TESTSPRITE_PROJECT_ID` environment variable → a `projectId` in `.testsprite/config.json` at the repo root → a name match from `testsprite project list` → asking you. The first two are conventions read by the *skill* (your agent), not by the CLI itself. Committing a pin removes the ambiguity:

```json .testsprite/config.json theme={null}
{ "projectId": "proj_8f0f6" }
```

**Keep credentials in place.** The skills preflight `testsprite auth status` and stop with a clear message if the CLI is missing or unauthenticated — they never install software or configure keys behind your back. If your agent reports either, re-run Step 1.

**Give it a deployed URL.** The CLI tests reachable `http(s)://` deployments and rejects `localhost`. If your change only runs locally, the agent will hand off to the [MCP Server](/mcp/getting-started/introduction) (which owns the localhost tunnel) when it's available, or honestly report the change as unverified — both are expected behavior, not failures.

**Heed the nudge.** If you run test or auth commands in a repo where no verify skill is installed, the CLI prints a one-line reminder to stderr. Silence it with `TESTSPRITE_NO_SKILL_WARNING=1` if you're deliberately driving the CLI by hand.

**Know the cost model.** Onboarding smoke-runs 2–3 tests, not the whole suite; full-suite runs are always your explicit call, with the credit cost stated up front. Frontend reruns of unchanged tests are free.

## Where to Go Next

<Columns cols={2}>
  <Card title="Coding Agent Integration" href="/cli/core/agent-integration" icon="robot">
    All eight agent targets, install flags, skill health checks, and the managed-section model for Codex
  </Card>

  <Card title="The Agent Loop" href="/cli/concepts/the-agent-loop" icon="arrows-rotate">
    The concepts behind create → run → read → fix → rerun and why coverage compounds
  </Card>

  <Card title="Creating Tests" href="/cli/core/creating-tests" icon="file-circle-plus">
    Plan files, code files, batch create, and dependency authoring — what your agent writes under the hood
  </Card>

  <Card title="Quickstart" href="/cli/getting-started/quickstart" icon="play">
    The same loop, driven by a human at the terminal
  </Card>
</Columns>