> ## 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.
# Projects
> List, inspect, create, and update the projects that hold your frontend and backend 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
```bash theme={null}
testsprite project list
```
Text output is a table with five columns:
```text theme={null}
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 ` | Number of results per page (1–100, default 25) |
| `--starting-token ` | Opaque cursor from a previous response to fetch the next page |
| `--max-items ` | 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.
```bash theme={null}
testsprite project list --page-size 10 --starting-token eyJsYXN...
```
## Getting a project
```bash theme={null}
testsprite project get
```
Text output:
```text theme={null}
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
```bash theme={null}
testsprite project create --type frontend --name "Checkout App" --url https://app.example.com
```
| Flag | Description |
| :--------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------- |
| `--type ` | **Required.** Project type |
| `--name ` | **Required.** Display name for the project |
| `--url ` | **Required for frontend.** Target URL — must be a public `http://` or `https://` address. Localhost and private IP ranges are not accepted |
| `--description ` | Optional description (≤ 2000 characters) |
| `--username ` | Optional basic-auth username for the target URL |
| `--password ` | Optional basic-auth password (prefer `--password-file` in scripts) |
| `--password-file ` | Read the password from a file — safer than inline for non-interactive use |
| `--instruction ` | Optional hint passed to the frontend plan-generation step |
| `--idempotency-key ` | Defaults to a UUIDv4 per invocation; pin a stable value for safe retries |
**Frontend project example:**
```bash theme={null}
testsprite project create \
--type frontend \
--name "Checkout App" \
--url https://app.example.com \
--description "End-to-end checkout and payment flows" \
--instruction "Focus on the cart and payment pages"
```
**Backend project example:**
```bash theme={null}
testsprite project create \
--type backend \
--name "Orders API" \
--description "REST API for order management"
```
`--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](/mcp/getting-started/introduction); see [Common Issues](/cli/troubleshooting/common-issues) if a URL is rejected.
## Updating a project
```bash theme={null}
testsprite project update --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 ` | New display name |
| `--url ` | New target URL (frontend only; same public-URL rules as create) |
| `--username ` | Updated basic-auth username |
| `--password ` | Updated password (prefer `--password-file`) |
| `--password-file ` | Read updated password from a file |
| `--description ` | Updated description (≤ 2000 characters) |
| `--instruction ` | Updated plan-generation hint |
| `--idempotency-key ` | Pin for safe retries |
## Where to Go Next
Author a frontend plan or backend code file inside a project
Project, test, run — definitions and relationships
Trigger runs and poll for verdicts
Full flag listing for every command