Command Reference - TestSprite Documentation

Every command follows the same pattern: global flags come first, then the subcommand and its own flags. Run any command with --help to see its flags inline.

Global flags

These flags must appear before the subcommand (e.g. testsprite --output json test run ...). They apply to every command.

Flag	Type	Default	Description
`--output <mode>`	`json\|text`	`text`	Output format. `json` is the stable agent/CI contract. Invalid value → exit 5.
`--profile <name>`	string	`default`	Configuration profile to use from `~/.testsprite/credentials`.
`--verbose`	flag	false	Human-readable retry/backoff/polling transitions to stderr. Less noisy than `--debug`.
`--debug`	flag	false	Print HTTP method/path, request ID, latency, and retry decisions to stderr.
`--dry-run`	flag	false	Skip network, credentials, and filesystem; emit a canned sample matching the OpenAPI contract. Learn any command offline without an API key.
`--request-timeout <seconds>`	number	`120`	Client-side per-request timeout (1–600 s). Does not affect `--wait` polling. Env: `TESTSPRITE_REQUEST_TIMEOUT_MS` (ms).
`-V, --version`	flag	—	Print version and exit 0.
`-h, --help`	flag	—	Print help and exit 0.

Command tree

testsprite
├── init                              One-shot onboarding (configure key + install agent skill)
├── auth
│   ├── configure                     Store an API key (validated against /me before writing)
│   ├── whoami  (alias: status)       Show user/key/scopes for active profile
│   └── logout                        Remove credentials for active profile
├── project
│   ├── list                          List projects
│   ├── get <project-id>              Get a project by id
│   ├── create                        Create a new project
│   └── update <project-id>           Update project metadata
├── test
│   ├── list                          List tests in a project (--project required)
│   ├── get <test-id>                 Get a test by id
│   ├── create                        Create a test (--code-file BE | --plan-from FE)
│   ├── create-batch                  Create multiple FE tests from plan specs
│   ├── update <test-id>              Update test metadata
│   ├── delete <test-id>              Permanently delete a test (--confirm required)
│   ├── delete-batch [test-ids...]    Bulk delete (--confirm required)
│   ├── steps <test-id>               List steps (cumulative; --run-id to scope)
│   ├── result <test-id>              Latest result (or --history for run list)
│   ├── run [test-id]                 Trigger a run (or --all for BE batch)
│   ├── wait <run-id>                 Wait for a run to reach terminal status
│   ├── rerun [test-ids...]           Re-execute as replay (FE no-credit; BE closure)
│   ├── code get <test-id>            Print generated test code
│   ├── code put <test-id>            Replace test code (etag/codeVersion guarded)
│   ├── plan put <test-id>            Replace an FE test's planSteps[]
│   ├── failure get <test-id>         Write failure bundle for latest failing run
│   ├── failure summary <test-id>     One-screen triage card
│   └── artifact get <run-id>         Download failure bundle for a SPECIFIC run
├── agent
│   ├── install                       Write the TestSprite skill file into a project
│   └── list                          List supported agent targets
└── usage  (alias: credits)           Show credit balance & plan info

Commands

init — one-shot onboarding

Chains auth configure → auth whoami → agent install and prints a unified summary. Installs credentials and the coding-agent skill in one step.

testsprite init [options]

Flag	Description
`--api-key <key>`	API key to configure (skips the interactive prompt)
`--from-env`	Read `TESTSPRITE_API_KEY` from the environment instead of prompting
`--agent <target>`	Coding-agent target: `claude`, `cursor`, `cline`, `antigravity`, `codex` (default `claude`)
`--no-agent`	Skip the agent skill install — configure credentials only
`--force`	Overwrite an existing skill file (a `.bak` backup is kept)
`--dir <path>`	Project root for the skill install (default: cwd)
`-y, --yes`	Non-interactive: accept all defaults, never prompt

No TTY + no --api-key + no --from-env → exit 5. Use --from-env in CI.

Text output: TestSprite initialized. followed by profile, endpoint, scopes, agent result, and next steps.

auth — configure / whoami / logout

Manage API keys and profiles.auth configure — store an API key for the active profile. Validates against GET /me before writing; never overwrites a working profile with a rejected key.

testsprite auth configure [--from-env]

Flag	Description
`--from-env`	Read `TESTSPRITE_API_KEY` from the environment

Text output: Profile "<name>" configured. Endpoint: <url>

auth whoami (alias: auth status) — show the user, API key, and scopes for the active profile. No flags.

testsprite auth whoami

Text output lines: userId / name / email / keyId / endpoint / env / scopes. Prints a note: line if write or run scopes are missing.

auth logout — remove credentials for the active profile. No flags.

testsprite auth logout

project — list / get / create / update

Manage projects. A project is a named container with a target URL (frontend) or codebase (backend).project list

testsprite project list [options]

Flag	Description
`--page-size <n>`	Items per page (1–100, default 25)
`--starting-token <token>`	Opaque cursor from a previous list response
`--max-items <n>`	Stop after this many items across auto-paged pages

Text columns: ID NAME TYPE FROM CREATED. Appends nextToken: <token> when a next page exists.

project get <project-id> — no flags. Text: id / name / type / createdFrom / createdAt / updatedAt.

testsprite project get <project-id>

project create

testsprite project create --type <frontend|backend> --name <name> [options]

Flag	Required	Description
`--type <frontend\|backend>`	Yes	Project type
`--name <name>`	Yes	Display name
`--url <url>`	Yes (FE)	Public http/https URL — no localhost or private IPs
`--description <text>`	No	Up to 2000 characters
`--username <user>`	No	Optional auth credential
`--password <pw>`	No	Optional auth credential
`--password-file <path>`	No	Read password from file (use this for non-interactive)
`--instruction <text>`	No	Optional FE plan-gen instruction hint
`--idempotency-key <token>`	No	Pin for safe retries (defaults to a UUIDv4 per invocation)

project update <project-id> — flags: --name, --url, --username, --password, --password-file, --description, --instruction, --idempotency-key. At least one mutable flag required (else exit 5).

testsprite project update <project-id> --name "New Name"

test create — create a single test

Create a test from saved code (--code-file) or an agent-supplied plan (--plan-from, frontend only). Combine with --run --wait to create and block for a verdict in one command.

testsprite test create --project <id> --type <frontend|backend> --name <name> [options]

Flag	Required	Description
`--project <id>`	Yes (code-file path)	Project to create the test in
`--type <frontend\|backend>`	Yes (code-file path)	Test type
`--name <name>`	Yes (code-file path)	Title (≤ 200 characters)
`--code-file <path>`	—	File with test code (≤ 350 KB). Mutually exclusive with `--plan-from`.
`--plan-from <path>`	—	JSON with full FE test definition: `projectId`, `type`, `name`, `planSteps[]` (≤ 256 KB). In this mode `--project`/`--type`/`--name`/`--description`/`--priority` are ignored.
`--description <text>`	No	Up to 2000 characters
`--priority <p0\|p1\|p2\|p3>`	No	Test priority
`--run`	No	After create, trigger the test
`--wait`	No	With `--run`: poll until terminal
`--timeout <s>`	No	With `--run --wait`: max seconds (default 600)
`--target-url <url>`	No	With `--run`: override project default URL
`--idempotency-key <token>`	No	1–256 ASCII; pin for safe retries
`--produces <var>`	No (BE only)	Variable this test captures; repeatable. Drives wave ordering on `run --all`.
`--needs <var>`	No (BE only)	Variable this test consumes; repeatable
`--category <str>`	No (BE only)	Use `teardown` or `cleanup` to mark a final-wave cleanup test

Output (no --run): { testId, type, codeVersion, createdAt, dashboardUrl? }. With --run --wait, merges a run object.

--plan-from and --code-file are mutually exclusive. --produces, --needs, and --category only apply to backend tests using --code-file.

test create-batch — bulk create FE tests

Create multiple frontend tests from a JSONL of plan specs or a directory of plan files.

testsprite test create-batch --plans <path> [options]

Flag	Required	Description
`--plans <path>`	Yes (XOR `--plan-from-dir`)	JSONL file, one plan spec per line (≤ 50 specs, ≤ 5 MB)
`--plan-from-dir <dir>`	Yes (XOR `--plans`)	Directory of `*.json` plan files, sorted by filename (≤ 50 files, ≤ 5 MB total)
`--run`	No	Trigger each test after creation
`--wait`	No	With `--run`: poll until all terminal
`--timeout <s>`	No	Default 600
`--target-url <url>`	No	Override project default URL
`--max-concurrency <n>`	No	Max in-flight triggers (1–100, default 50). Server caps at 60/min/key; CLI throttles to 50/min.
`--idempotency-key <token>`	No	Batch-level idempotency key

test update — update test metadata

Update a test’s name, description, or priority.

testsprite test update <test-id> [options]

Flag	Description
`--name <name>`	New title
`--description <text>`	Up to 2000 characters
`--priority <p0\|p1\|p2\|p3>`	Test priority
`--idempotency-key <token>`	For safe retries

test delete & delete-batch — permanently remove tests

test delete <test-id> — permanently delete one test. --confirm is required.

testsprite test delete <test-id> --confirm

Flag	Required	Description
`--confirm`	Yes	Explicit confirmation for the destructive operation
`--idempotency-key <token>`	No	For safe retries

test delete-batch — bulk delete by ID list, project, or status filter.

testsprite test delete-batch [test-ids...] --confirm [options]

Flag	Required	Description
`--confirm`	Yes	Required for any destructive operation
`--all`	No	Delete all tests in resolved project (requires `--project`)
`--project <id>`	No	Required with `--all`
`--status <list>`	No	With `--all`: only delete matching statuses (comma-separated)

Prints Deleted N, Skipped M, Failed K. A 404 counts as skipped, not an error. Exit 0 all deleted; 1 some failed; 5 validation.

test list / get — read tests

test list — list tests in a project. --project is required.

testsprite test list --project <id> [options]

Flag	Description
`--project <id>`	Required
`--type <frontend\|backend>`	Filter by type
`--created-from <portal\|mcp\|cli>`	Filter by author surface
`--status <list>`	Comma-separated: `draft, ready, queued, running, passed, failed, blocked, cancelled, unknown`
`--page-size <n>`	Default 25
`--starting-token <token>`	Pagination cursor
`--max-items <n>`	Stop after this many total items

test get <test-id> — no flags. JSON:

{ id, projectId, projectName?, name, type, createdFrom, status, createdAt, updatedAt, planStepCount?, details?, priority? }

testsprite test get <test-id>

test steps — list execution steps

List the cumulative step log for a test across every run. Use --run-id to scope to one run.

testsprite test steps <test-id> [options]

Flag	Description
`--run-id <id>`	Scope steps to a specific run
`--page-size <n>`	Default 25
`--max-items <n>`	Stop after this many items
`--starting-token <token>`	Pagination cursor

test result — latest result and run history

Show the latest result for a test, or list prior runs with --history.

testsprite test result <test-id> [options]

Flag	Description
`--include-analysis`	Attach inline `analysis` block: `rootCauseHypothesis`, `recommendedFixTarget`, `failureKind`, `snapshotId`
`--history`	List prior runs instead of latest result
`--source <cli\|portal\|mcp\|schedule\|github_action>`	With `--history`: filter by trigger source
`--since <dur>`	With `--history`: lower bound on `createdAt` — `24h`, `7d`, or ISO timestamp
`--page-size <n>`	Default 20 (1–100)
`--cursor <token>`	Pagination cursor

Default JSON: CliLatestResult. With --history: { runs: RunHistoryItem[], nextCursor: string|null }.

test run — trigger a run

Trigger a test run. Combine with --wait to block until terminal. Use --all --project <id> for a wave-ordered batch run of all backend tests.

testsprite test run [test-id] [options]

Flag	Required	Description
`--all`	No	Run all BE tests in project in wave order. Mutually exclusive with `<test-id>`.
`--project <id>`	Yes (with `--all`)	Project to run
`--wait`	No	Poll until terminal or `--timeout`
`--timeout <s>`	No	1–3600, default 600
`--target-url <url>`	No	Override project default URL (no localhost or private IPs)
`--idempotency-key <key>`	No	1–256 characters
`--filter <substr>`	No	With `--all`: only tests whose name contains this string (case-insensitive)
`--max-concurrency <n>`	No	With `--all --wait`: max in-flight polls (1–100, default 50)

On failure, blocked, or cancelled: run testsprite test artifact get <run-id> to pull the failure bundle.

test wait — wait for a run

Wait for a run already in flight to reach a terminal status. Use this to resume after a --timeout on test run.

testsprite test wait <run-id> [options]

Flag	Description
`--timeout <s>`	1–3600, default 600

Exit codes: 0 passed; 1 failed/blocked/cancelled; 3 auth; 4 run not found; 7 timeout; 10 transport.Text output: runId / status / targetUrl / codeVersion / startedAt / finishedAt / steps / dashboard.

test rerun — cheap replay

Re-execute a test as a replay. Frontend replays the saved script (no credit charge). Backend re-runs the full dependency closure (producer + teardown tests).

testsprite test rerun [test-ids...] [options]

Flag	Description
`--all`	Rerun all tests in resolved project (requires `--project`)
`--project <id>`	Required with `--all`
`--skip-terminal`	With `--all`: skip tests already in a terminal status
`--status <list>`	With `--all`: only matching statuses
`--filter <substr>`	With `--all`: name substring match (case-insensitive)
`--wait`	Poll until terminal
`--timeout <s>`	1–3600, default 600
`--no-auto-heal`	Opt out of AI heal-on-drift for this FE rerun (default: auto-heal ON)
`--skip-dependencies`	BE only: rerun only the named test without the producer/teardown closure
`--max-concurrency <n>`	1–100, default 50
`--idempotency-key <key>`	For safe retries

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

test code — get / put

test code get <test-id> — print the generated test code to stdout, or write to a file.

testsprite test code get <test-id> [--out <path>]

Flag	Description
`--out <path>`	Write to file instead of stdout

JSON: { testId, language, framework, code, codeVersion }. Large code files are fetched transparently — you always receive the full code.

test code put <test-id> — replace test code with ETag-guarded optimistic concurrency.

testsprite test code put <test-id> --code-file <path> [options]

Flag	Required	Description
`--code-file <path>`	Yes	Replacement code file (≤ 350 KB)
`--expected-version <v>`	No	Expected current `codeVersion` (e.g. `v3`). Fails with a conflict (exit 6) if the test changed since you fetched it. Mutually exclusive with `--force`.
`--force`	No	Overwrite regardless of current version (audit-logged). Mutually exclusive with `--expected-version`.
`--language <typescript\|javascript\|python>`	No	Override stored language
`--idempotency-key <token>`	No	For safe retries

test plan put — replace FE test steps

Replace a frontend test’s planSteps[]. Returns 400 for backend tests — use test code put instead.

testsprite test plan put <test-id> --steps <path> [options]

Flag	Required	Description
`--steps <path>`	Yes	JSON file: `{ planSteps: [...] }` (≤ 200 steps, ≤ 256 KB)
`--expected-step-count <n>`	No	Optional concurrency check — returns 412 if current step count differs
`--idempotency-key <token>`	No	For safe retries

test failure — get / summary

test failure get <test-id> — write a self-contained failure-context bundle for the latest failing run.

testsprite test failure get <test-id> [--out <dir>] [--failed-only]

Flag	Description
`--out <dir>`	Directory to write the bundle into (default: print wire envelope to stdout)
`--failed-only`	Keep only the failed step plus its immediate neighbors (±1)

The bundle contains: failing step + neighbors, DOM snapshots rendered as text for agents, the test source, a root-cause hypothesis, a recommended fix target — all sharing one snapshotId.

test failure summary <test-id> — print a one-screen triage card. No flags.

testsprite test failure summary <test-id>

JSON: { testId, status, failureKind, snapshotId, rootCauseHypothesis, recommendedFixTarget }.

test artifact get — run-scoped failure bundle

Download the failure-context bundle for a specific run by runId. Unlike test failure get, this is immutable — a concurrent Portal or scheduled run cannot overwrite it.

testsprite test artifact get <run-id> [options]

Flag	Description
`--out <dir>`	Output directory (default: `./.testsprite/runs/<run-id>/`; parent must exist)
`--failed-only`	Keep only the failed step plus its immediate neighbors (±1)

Exit codes: 0 written; 3 auth; 4 not found/not ready/no failure; 5 validation; 6 conflict (snapshot in flight, retried once); 10 transport (.partial left on disk).

agent — install / list

agent install — write the TestSprite verification-loop skill file into a project for a coding agent. Pure local — no network, no credentials.

testsprite agent install [options]

Flag	Description
`--target <t>`	Agent target (repeatable/comma-separated; prompts if TTY): `claude`, `cursor`, `cline`, `antigravity`, `codex`
`--dir <path>`	Project root (default: cwd)
`--force`	Overwrite existing (a `.bak` backup is kept); for `codex`, replaces only the managed section

Supported targets:

Target	Status	Mode	Landing path
`claude`	GA	own-file	`.claude/skills/testsprite-verify/SKILL.md`
`antigravity`	experimental	own-file	`.agents/skills/testsprite-verify/SKILL.md`
`cursor`	experimental	own-file	`.cursor/rules/testsprite-verify.mdc`
`cline`	experimental	own-file	`.clinerules/testsprite-verify.md`
`codex`	experimental	managed-section	`AGENTS.md`

Exit 6 if any target is blocked (exists and differs, no --force).

agent list — list supported agent targets, their status, and landing paths. Pure local, no flags. Text columns: TARGET STATUS MODE PATH.

testsprite agent list

usage — credit balance and plan info

Show your account and plan info. Credit fields (credits, subPlan, creditsPerRun) appear when the backend supplies them.

testsprite usage

Alias: testsprite credits. Calls GET /me.

Where to Go Next

Configuration

Credentials file, profiles, environment variables, and the JSON output contract

Exit Codes & Errors

Every exit code, error code, and status value in one table

Creating Tests

How to author frontend and backend tests from the CLI

Running Tests

Triggering runs, polling, and pulling failure bundles

​Global flags

​Command tree

​Commands

​Where to Go Next

Configuration

Exit Codes & Errors

Creating Tests

Running Tests

Global flags

Command tree

Commands

Where to Go Next