Skip to main content

​
What is the TestSprite CLI?

The verification layer for the agentic coding era. TestSprite is the AI testing platform 100,000+ teams use to test their software — frontend and backend — in the cloud, against the live product, not mocks. The CLI puts that platform in your coding agent’s hands: structured output it can parse, exit codes it can branch on, and one self-consistent failure bundle it can act on — no dashboard scraping.
The CLI shares the same backend, projects, and tests as the Web Portal and the MCP Server. A test you create from the terminal shows up in the dashboard, and vice versa.
The --output json response shape and exit codes are a stable contract your agents and CI can rely on — designed to stay backward-compatible as the CLI grows.

​
Why a CLI for coding agents?

Every step between “agent writes code” and “agent reads what broke” is a manual context-transfer tax. The CLI removes it: your agent describes intent and reads results, never needing to know how the test was driven — only what a real user experienced.
Web Portal dashboard

The manual loop

Agent writes code → you run the app, click around, screenshot the result, paste it back, and type “the checkout button is broken on mobile.”

With the CLI

Agent describes intent → triggers a real cloud run → reads the verdict itself. No human in the middle.
What broke comes back as one self-consistent failure bundle the agent can act on — all anchored to the same snapshot. The CLI refuses to stitch data from two different runs, so an agent never reasons over a frankenstein context:
In the bundleWhat it contains
Failing stepThe exact step that broke, plus its neighbors for context.
DOM snapshotsThe DOM at the point of failure — your agent can read it without a vision model.
Fix guidanceA root-cause hypothesis and a recommended fix target.
Run any command offline before you have an API key. Prepend --dry-run to emit a canned sample matching the real response shape — no credentials needed. It’s the fastest way to learn the surface.

​
The verification loop

1

Install and onboard

Install once globally, then run testsprite init. It prompts for your API key, verifies it against the platform, and installs the verification skill into your agent’s project — so your agent already knows when and how to run tests.
npm install -g @testsprite/testsprite-cli
testsprite init
2

Describe a behavior and create + run a test

Describe the behavior you want to verify as a plan file — write it yourself, have your coding agent author it, or let TestSprite generate it. One command then creates the test, triggers a real cloud run against your live app, and blocks until a verdict:
testsprite test create \
  --project proj_8f0f6 --type frontend \
  --plan-from ./checkout-flow.plan.json \
  --run --wait --output json
Exit 0 means the test passed, exit 1 means it failed — you (or your agent) branch on the exit code.
3

On failure, read the one bundle

Pull a self-contained failure bundle — no back-and-forth across endpoints:
testsprite test failure get test_3a9f21c7 --out ./.testsprite/failure
The bundle contains the failing step and its neighbors, DOM snapshots rendered as text, the test source, a root-cause hypothesis, and a recommended fix target.
4

Fix and rerun — coverage compounds

After fixing the code, replay the test cheaply (frontend replay costs no credits):
testsprite test rerun test_3a9f21c7 --wait
Every pass is banked into the durable suite. Next time you ship a change, you rerun rather than recreate — coverage compounds into a lasting record of every requirement you’ve verified, far bigger than any context window.

​
Who It’s For

AudienceWhat they get
AI coding agents
Primary		Claude Code, Codex, Cursor, Cline, Antigravity, and similar — the agent drives the loop without a human in the middle.
Developers at a terminalThe same surface, with predictable commands, consistent flags, and machine-readable output.
CI pipelinesStable --output json contract, stable exit codes, and non-interactive --from-env auth.

​
One Platform, Three Surfaces

All three surfaces hit the same backend and share the same tests, projects, and runs. Choose by context:
  • What it’s for: Humans — visual project setup, PRD uploads, test exploration, dashboards, scheduling, billing, and team management.
  • Best when: You’re starting a new project, reviewing test coverage visually, managing schedules and monitors, or handling billing and credentials.
  • Limitations: Not scriptable; not designed for agent-driven loops.

Go to Web Portal docs

CapabilityWeb PortalMCP ServerCLI
Create and run tests
Visual dashboards & scheduling——
localhost targets via tunnel——
Agent-driven—
Scriptable / CI——
Structured failure bundles—
Billing & org management——

​
Where to Go Next

Installation

Install the CLI and sign in in under 2 minutes

Quickstart

Create a test, run it, and read what broke — end to end

Key Terms

Projects, tests, runs, and the concepts behind them

Command Reference

Every command, flag, and exit code