Skip to main content
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.

​
Command tree

​
Commands

Configures your API key (validated against GET /me before writing) and installs the coding-agent skill in one step, then prints a unified summary. This is the only command that writes credentials.
No TTY + no --api-key + no --from-env → exit 5. Use --from-env in CI.
Text output: TestSprite initialized. followed by profile, scopes, agent result, and next steps.
Runs a fixed checklist — CLI version, Node.js runtime, active profile, API endpoint, credentials, live connectivity (a real GET /me call that validates the key), and whether the verify skill is installed in the current project — and prints an OK/WARN/FAIL report. No flags beyond the global flags.
Exits non-zero only when a check FAILs — warnings (like a missing skill install) don’t fail the process — so it drops cleanly into a preflight step:
Inspect and remove credentials. Credentials are written by setup (add --no-agent for credentials only).auth status — show the user, API key, env, and scopes for the active profile. No flags.
Text output lines: userId / name / email / keyId / env / scopes. Prints a note: line if write or run scopes are missing.
auth remove — remove credentials for the active profile. No flags.
Manage projects. A project is a named container with a target URL (frontend) or codebase (backend).project list
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.
project create
project update <project-id> — flags: --name, --url, --username, --password, --password-file, --instruction, --idempotency-key. At least one mutable flag required (else exit 5).
project delete <project-id> — permanently delete a project and everything under it: its frontend/backend sub-projects, all their tests, and backend fixtures (mirrors the Portal’s cascade delete). There is no restore window. --confirm is required — the CLI never prompts; absent it, exit 5 with a local validation error. --dry-run previews the response shape without a network call. Exit codes: 0 success, 3 auth, 4 not found (or already deleted), 5 validation.
Set the static credential TestSprite injects into every backend test run for this project — a Bearer token, an API key, HTTP Basic, or none.
Configure recurring-token auto-refresh login for backend tests: the CLI’s backend runner fetches a fresh token on every run and injects it into each backend test, instead of relying on one static credential.
--method password flags: --login-url, --login-method <POST\|PUT>, --login-content-type, --login-body-template (supports {{username}}/{{password}} placeholders), --username, --password (or --password-file), --token-path <jsonpath>.--method refresh_token flags: --token-endpoint, --client-id, --client-secret (or --client-secret-file), --refresh-token (or --refresh-token-file), --scope.--method aws_cognito_refresh flags: --region, plus the refresh-token flags above.
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.
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.
Create multiple frontend tests from a JSONL of plan specs or a directory of plan files.
Print a schema-correct starter test — a frontend plan JSON by default, or a backend Python skeleton — so a first test never starts from hand-copied JSON. Pure-local: no network, no credentials, no filesystem reads.
The frontend scaffold is a ready-to-edit CliPlanInput — the exact shape --plan-from ingests — with projectId pre-filled from TESTSPRITE_PROJECT_ID when set, or a placeholder pointing at testsprite project list otherwise.
Run the same validators test create uses against local plan/steps files, but collect every problem instead of failing on the first one. No network, no credentials.
Exactly one of the four flags is required. JSON output: { checked, valid, issues: [{ file, field, reason }] }. Exit 0 when everything is valid, 5 otherwise — drop it into a pre-commit hook or a CI step before test create-batch.
Update a test’s name, description, or priority — and, for backend tests, its dependency declarations. Updated declarations are echoed back by test get.
test delete <test-id> — permanently delete one test. --confirm is required.
test delete-batch — bulk delete by ID list, project, or status filter.
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 — list tests in a project. --project is required.
test get <test-id> — no flags. JSON: { id, projectId, projectName?, name, type, createdFrom, status, createdAt, updatedAt, planStepCount?, details?, priority?, produces?, consumes?, category? } (the last three appear on backend tests with dependency declarations).
List the cumulative step log for a test across every run. Use --run-id to scope to one run.
Show the latest result for a test, or list prior runs with --history.
Default JSON: CliLatestResult. With --history: { runs: RunHistoryItem[], nextCursor: string|null }. Backend tests also carry apiOutput (the run’s captured stdout) and trace (Python traceback) — full content in JSON; text mode prints a bounded 20-line tail of each.
Isolate what regressed between two runs — usually the first question when a suite goes red: “what changed since the last green run?”
No flags. Compares verdict, failureKind, failedStepIndex, per-step status flips, and codeVersion drift between the two runs. If the runs belong to different tests, the CLI still compares them but prints a warning — the deltas may not be meaningful.Exit 0 when the two verdicts match, 1 when they differ — so it’s scriptable as a regression gate:
Trigger a test run. Combine with --wait to block until terminal. Use --all --project <id> for a wave-ordered batch run of every test in the project.
--all triggers every test in the project (each billed like any run). A project holds a single test type — frontend or backend — so don’t mix both. On the legacy backend-only batch engine, frontend tests are skipped and reported in skippedFrontend with an advisory — run those individually with test run <test-id>.
On failure, blocked, or cancelled: run testsprite test artifact get <run-id> to pull the failure bundle.
Wait for a run already in flight to reach a terminal status. Use this to resume after a --timeout on test run or test rerun. Accepts several run IDs at once.
One run ID (unchanged shape): 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.Several run IDs: the runs poll concurrently under the one shared --timeout, and the output is a { results, summary } envelope instead — the worst status across all members decides the exit code, so one command can wait on everything a batch run or rerun printed a test wait <run-id> hint for.
Exit codes (multi-id): 0 all passed; 1 any failed/blocked/cancelled; 3 auth; 7 any timeout or per-member poll error (recorded as error:<CODE> in that run’s row); 10 transport.
Cancel one or more runs server-side. This is the real stop button — Ctrl-C during a --wait only detaches the CLI while the run keeps executing and billing.
No flags beyond the global ones. Semantics: the run flips to cancelled, the test is immediately re-runnable, the test’s last verdict is untouched, and already-charged credits are not refunded. Re-cancelling an already-cancelled run is a success (idempotent) with an [advisory] stderr line.One run ID: exit codes 0 cancelled or already cancelled; 4 run not found; 6 run already finished (passed/failed/blocked).Several run IDs: output is a { cancelled, alreadyCancelled, conflicts, notFound, errors } summary. Exit precedence: any notFound → 4; else any errors → 1; else any conflicts → 6; else 0.

Cancelling a Run

Detach vs cancel, billing semantics, and the CI cleanup pattern
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).
Auto-heal is on by default and uses a small amount of credit only when it actually repairs a step — see Rerun & Auto-Heal.
Replay a test several times with auto-heal forced off (a strict, verbatim replay) and report how stable it is — the fast way to tell “flaky test” from “real regression.”
JSON output: { testId, runs, passed, failed, stableRatio, verdict, failures: [...] }.Exit codes: 0 stable (every attempt passed); 1 flaky or failing; 3 auth error; 4 the test has no replayable run yet — trigger testsprite test run <test-id> first; 5 validation error.
Frontend replays are free verbatim script replays. Backend replays re-run the full dependency closure and may cost credits — the CLI prints a one-line advisory before the first attempt.
test code get <test-id> — print the generated test code to stdout, or write to a file.
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.
Replace a frontend test’s planSteps[]. Returns 400 for backend tests — use test code put instead.
test failure get <test-id> — write a self-contained failure-context bundle for the latest failing run.
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.
JSON: { testId, status, failureKind, snapshotId, rootCauseHypothesis, recommendedFixTarget }.
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.
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 — write the TestSprite skill files into a project for a coding agent: testsprite-verify (verification loop) and testsprite-onboard (first-run setup) by default. Pass --skill to install a subset. Pure local — no network, no credentials.
Supported targets:{skill} is testsprite-verify or testsprite-onboard. Own-file targets get one file per installed skill; codex merges every installed skill’s contribution into the single managed section.Exit 6 if any target is blocked (exists and differs, no --force).
agent list — list supported agent targets, their status, and landing paths (one row per target × installed skill). Pure local, no flags. Text columns: TARGET SKILL STATUS MODE PATH.
agent status — check installed skill files against what this CLI version would install. Pure local, no network.
Each artifact is classified as ok, stale, modified, unmarked, absent, or corrupt (corrupt is codex-only). Exit 1 when anything needs attention (any state other than ok/absent), so it’s CI-gateable.
Show your account and plan info. Credit fields (credits, subPlan, creditsPerRun) appear when the backend supplies them.
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