Projects

List, inspect, create, and update the typed (frontend or backend) projects that hold your tests.

A project is the top-level container in TestSprite. It carries a name, a type (frontend or backend), and — for frontend projects — a target URL that TestSprite opens when it runs your tests. Every test belongs to exactly one project, identified by its projectId.

Projects created or updated through the CLI are immediately visible in the Web Portal, and vice versa. All surfaces share the same data.

Listing projects

testsprite project list

Text output is a table with five columns:

ID              NAME               TYPE       FROM     CREATED
proj_8f0f6      Checkout App       frontend   cli      2026-05-10
proj_a3c12      Orders API         backend    portal   2026-04-22

Flag	Description
--page-size <n>	Number of results per page (1–100, default 25)
--starting-token <token>	Opaque cursor from a previous response to fetch the next page
--max-items <n>	Stop after this many total items across auto-paged requests

When there are more results, the CLI appends a nextToken line to the text output. Pass that value as --starting-token on the next call to continue.

testsprite project list --page-size 10 --starting-token eyJsYXN...

Getting a project

testsprite project get <project-id>

Text output:

id          proj_8f0f6
name        Checkout App
type        frontend
createdFrom cli
createdAt   2026-05-10T14:32:00Z
updatedAt   2026-05-11T09:15:00Z

Creating a project

testsprite project create --type frontend --name "Checkout App" --url https://app.example.com

Flag	Description
--type <frontend|backend>	Required. Project type
--name <name>	Required. Display name for the project
--url <url>	Required for frontend. Target URL — must be a public http:// or https:// address. Localhost and private IP ranges are not accepted
--username <user>	Optional basic-auth username for the target URL
--password <pw>	Optional basic-auth password (prefer --password-file in scripts)
--password-file <path>	Read the password from a file — safer than inline for non-interactive use
--instruction <text>	Optional hint passed to the frontend plan-generation step
--idempotency-key <token>	Defaults to a UUIDv4 per invocation; pin a stable value for safe retries

Frontend project example:

testsprite project create \
  --type frontend \
  --name "Checkout App" \
  --url https://app.example.com \
  --instruction "Focus on the cart and payment pages"

Backend project example:

testsprite project create --type backend --name "Orders API"

--url must be a public http(s) address — localhost and private IPs are rejected before any network call. To test a local app, use the MCP Server; see Common Issues if a URL is rejected.

Updating a project

testsprite project update <project-id> --name "Checkout App v2"

You must pass at least one mutable flag — an update with no changes exits with a validation error (exit 5).

Flag	Description
--name <name>	New display name
--url <url>	New target URL (frontend only; same public-URL rules as create)
--username <user>	Updated basic-auth username
--password <pw>	Updated password (prefer --password-file)
--password-file <path>	Read updated password from a file
--instruction <text>	Updated plan-generation hint
--idempotency-key <token>	Pin for safe retries

Backend test credentials

Backend projects can inject auth into every backend test run, either as a static credential or as a recurring, auto-refreshed token:

# Static credential (free tier) — Bearer token, API key, or Basic auth
testsprite project credential <project-id> --type "Bearer token" --credential-file ./token.txt

# Recurring-token auto-refresh login (Pro) — fetches a fresh token on every run
testsprite project auto-auth <project-id> --method refresh_token --inject bearer \
  --token-endpoint https://auth.example.com/oauth/token \
  --client-id my-client-id --client-secret-file ./client-secret.txt \
  --refresh-token-file ./refresh-token.txt

Command Reference

Full flag reference for project credential and project auto-auth

Where to Go Next

Creating Tests

Author a frontend plan or backend code file inside a project

Key Terms

Project, test, run — definitions and relationships

Running Tests

Trigger runs and poll for verdicts

Command Reference

Full flag listing for every command