> ## 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.

# Command Reference

> Every testsprite command, flag, and output shape in one place.

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

```text theme={null}
testsprite
├── setup                             One-shot onboarding (configure key + install agent skill)
├── doctor                            Diagnose environment: version, Node, profile, endpoint, auth, skill
├── auth
│   ├── status                        Show user/key/env/scopes for active profile
│   └── remove                        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
│   ├── delete <project-id>           Permanently delete a project and everything under it
│   ├── credential <project-id>       Set the static backend credential for BE tests (free tier)
│   └── auto-auth <project-id>        Configure recurring-token auto-refresh login for BE tests (Pro)
├── 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
│   ├── scaffold                      Emit a schema-correct starter plan or BE code skeleton (local)
│   ├── lint                          Validate plan/steps files offline before creating (local)
│   ├── 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)
│   ├── diff <run-a> <run-b>          Compare two runs' verdicts and step deltas
│   ├── run [test-id]                 Trigger a run (or --all for a wave-ordered batch)
│   ├── wait <run-id...>              Wait for one or more runs to reach terminal status
│   ├── cancel <run-id...>            Cancel queued/running runs (Ctrl-C only detaches)
│   ├── rerun [test-ids...]           Re-execute as replay (FE no-credit; BE closure)
│   ├── flaky <test-id>               Replay a test N times and report a stability score
│   ├── 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 files into a project
│   ├── list                          List supported agent targets
│   └── status                        Check installed skill files against this CLI version
└── usage  (alias: credits)           Show credit balance & plan info
```

## Commands

<AccordionGroup>
  <Accordion title="setup — one-shot onboarding">
    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.

    ```bash theme={null}
    testsprite setup [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`, `kiro`, `windsurf`, `copilot`, `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                                                                         |

    <Note>
      No TTY + no `--api-key` + no `--from-env` → exit 5. Use `--from-env` in CI.
    </Note>

    Text output: `TestSprite initialized.` followed by profile, scopes, agent result, and next steps.
  </Accordion>

  <Accordion title="doctor — environment diagnostic">
    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](#global-flags).

    ```bash theme={null}
    testsprite doctor
    ```

    ```text theme={null}
    TestSprite doctor

      [OK]   CLI version    0.3.0
      [OK]   Node.js        v22.9.0 (>=20 required)
      [OK]   Profile        default
      [OK]   API endpoint   https://api.testsprite.com
      [OK]   Credentials    API key configured (profile "default")
      [OK]   Connectivity   reached GET /me, API key accepted (userId u_01abc...)
      [WARN] Verify skill   not installed here; run `testsprite setup` so your agent verifies its changes

    0 failure(s), 1 warning(s).
    ```

    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:

    ```bash theme={null}
    testsprite doctor && testsprite test run test_3a9f21c7 --wait
    ```
  </Accordion>

  <Accordion title="auth — status / remove">
    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.

    ```bash theme={null}
    testsprite auth status
    ```

    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.

    ```bash theme={null}
    testsprite auth remove
    ```
  </Accordion>

  <Accordion title="project — list / get / create / update / delete">
    Manage projects. A project is a named container with a target URL (frontend) or codebase (backend).

    **project list**

    ```bash theme={null}
    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`.

    ```bash theme={null}
    testsprite project get <project-id>
    ```

    ***

    **project create**

    ```bash theme={null}
    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        |
    | `--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`, `--instruction`, `--idempotency-key`. At least one mutable flag required (else exit 5).

    ```bash theme={null}
    testsprite project update <project-id> --name "New Name"
    ```

    ***

    **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.

    ```bash theme={null}
    testsprite project delete <project-id> --confirm
    testsprite project delete <project-id> --dry-run --output json
    ```
  </Accordion>

  <Accordion title="project credential — static backend auth (free tier)">
    Set the static credential TestSprite injects into every backend test run for this project — a Bearer token, an API key, HTTP Basic, or none.

    ```bash theme={null}
    testsprite project credential <project-id> --type <type> [options]
    ```

    | Flag                        | Required                        | Description                                                     |
    | :-------------------------- | :------------------------------ | :-------------------------------------------------------------- |
    | `--type <type>`             | **Yes**                         | One of `public`, `"Bearer token"`, `"API key"`, `"basic token"` |
    | `--credential <value>`      | **Yes**, unless `--type public` | The credential value                                            |
    | `--credential-file <path>`  | No                              | Read the credential from a file instead of `--credential`       |
    | `--idempotency-key <token>` | No                              | For safe retries                                                |

    ```bash theme={null}
    testsprite project credential proj_2c4a1 --type "Bearer token" --credential-file ./api-token.txt
    ```
  </Accordion>

  <Accordion title="project auto-auth — recurring-token login (Pro)">
    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.

    ```bash theme={null}
    testsprite project auto-auth <project-id> --method <method> --inject <where> [options]
    ```

    | Flag                  | Required | Description                                                             |
    | :-------------------- | :------- | :---------------------------------------------------------------------- |
    | `--method <method>`   | **Yes**  | `password` \| `refresh_token` \| `aws_cognito_refresh`                  |
    | `--inject <where>`    | **Yes**  | Where the token lands on each request: `bearer` \| `header` \| `cookie` |
    | `--disable`           | No       | Turn auto-auth off (keeps the stored config)                            |
    | `--inject-key <name>` | No       | Header/cookie name when `--inject` is `header`/`cookie`                 |

    `--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.

    ```bash theme={null}
    testsprite project auto-auth proj_2c4a1 \
      --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
    ```
  </Accordion>

  <Accordion title="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.

    ```bash theme={null}
    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.

    <Note>
      `--plan-from` and `--code-file` are mutually exclusive. `--produces`, `--needs`, and `--category` only apply to backend tests using `--code-file`.
    </Note>
  </Accordion>

  <Accordion title="test create-batch — bulk create FE tests">
    Create multiple frontend tests from a JSONL of plan specs or a directory of plan files.

    ```bash theme={null}
    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                                                                     |
  </Accordion>

  <Accordion title="test scaffold — emit a starter test definition">
    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.

    ```bash theme={null}
    testsprite test scaffold [options]
    ```

    | Flag                         | Description                                    |
    | :--------------------------- | :--------------------------------------------- |
    | `--type <frontend\|backend>` | Which scaffold to emit (default `frontend`)    |
    | `--out <path>`               | Write the scaffold to a file instead of stdout |
    | `--force`                    | Overwrite an existing `--out` file             |

    ```bash theme={null}
    testsprite test scaffold > first-test.plan.json
    testsprite test scaffold --type backend --out tests/health.py
    ```

    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.
  </Accordion>

  <Accordion title="test lint — validate plan/steps files offline">
    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.

    ```bash theme={null}
    testsprite test lint [options]
    ```

    | Flag                    | Description                                                                   |
    | :---------------------- | :---------------------------------------------------------------------------- |
    | `--plan-from <file>`    | Single plan JSON file                                                         |
    | `--plan-from-dir <dir>` | Directory of `*.json` plan files (each checked; every file's errors reported) |
    | `--plans <file>`        | JSONL file, one plan spec per line (each line checked)                        |
    | `--steps <file>`        | Plan-steps JSON file (the shape `test plan put` ingests)                      |

    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`.

    ```bash theme={null}
    testsprite test lint --plan-from-dir ./plans/
    ```
  </Accordion>

  <Accordion title="test update — update test metadata & BE dependencies">
    Update a test's name, description, or priority — and, for **backend tests**, its dependency declarations. Updated declarations are echoed back by `test get`.

    ```bash theme={null}
    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                                                         |
    | `--produces <var>`                   | BE only, repeatable — variable this test produces for the wave engine |
    | `--needs <var>`                      | BE only, repeatable — variable this test consumes                     |
    | `--category <setup\|main\|teardown>` | BE only — wave-ordering category                                      |
    | `--idempotency-key <token>`          | For safe retries                                                      |
  </Accordion>

  <Accordion title="test delete & delete-batch — permanently remove tests">
    **test delete `<test-id>`** — permanently delete one test. `--confirm` is required.

    ```bash theme={null}
    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.

    ```bash theme={null}
    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.
  </Accordion>

  <Accordion title="test list / get — read tests">
    **test list** — list tests in a project. `--project` is required.

    ```bash theme={null}
    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?, produces?, consumes?, category? }` (the last three appear on backend tests with dependency declarations).

    ```bash theme={null}
    testsprite test get <test-id>
    ```
  </Accordion>

  <Accordion title="test steps — list execution steps">
    List the cumulative step log for a test across every run. Use `--run-id` to scope to one run.

    ```bash theme={null}
    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             |
  </Accordion>

  <Accordion title="test result — latest result and run history">
    Show the latest result for a test, or list prior runs with `--history`.

    ```bash theme={null}
    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 }`. 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.
  </Accordion>

  <Accordion title="test diff — compare two runs">
    Isolate what regressed between two runs — usually the first question when a suite goes red: "what changed since the last green run?"

    ```bash theme={null}
    testsprite test diff <run-a> <run-b>
    ```

    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:

    ```bash theme={null}
    testsprite test diff run_5c1d9a2b run_7f2e1c04 --output json
    ```
  </Accordion>

  <Accordion title="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 every test in the project.

    ```bash theme={null}
    testsprite test run [test-id] [options]
    ```

    | Flag                         | Required               | Description                                                                             |
    | :--------------------------- | :--------------------- | :-------------------------------------------------------------------------------------- |
    | `--all`                      | No                     | Run all tests in the 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). No effect with `--all`.     |
    | `--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)                            |
    | `--report <format>`          | No                     | With `--all --wait`: write a JUnit XML sidecar after polling. Only `junit` is accepted. |
    | `--report-file <path>`       | No                     | Output path for `--report` (required when `--report` is set; written atomically)        |
    | `--report-suite-name <name>` | No                     | Override the JUnit `<testsuite name="...">` (default `testsprite:<projectId>`)          |

    <Note>
      `--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>`.
    </Note>

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

  <Accordion title="test wait — wait for one or more runs">
    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.

    ```bash theme={null}
    testsprite test wait <run-id...> [options]
    ```

    | Flag                    | Description                                                             |
    | :---------------------- | :---------------------------------------------------------------------- |
    | `--timeout <s>`         | 1–3600, default 600. Shared across every run ID when several are given. |
    | `--max-concurrency <n>` | With several run IDs: max concurrent polls (1–100, default 10)          |

    **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.

    ```bash theme={null}
    testsprite test wait run_5c1d9a2b run_7f2e1c04 run_9a01b3e5 --output json
    ```

    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.
  </Accordion>

  <Accordion title="test cancel — stop queued/running runs">
    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.

    ```bash theme={null}
    testsprite test cancel <run-id...>
    ```

    No flags beyond the global ones. Semantics: the run flips to <kbd>cancelled</kbd>, 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.

    <Card title="Cancelling a Run" href="/cli/core/cancelling-runs" icon="circle-stop">
      Detach vs cancel, billing semantics, and the CI cleanup pattern
    </Card>
  </Accordion>

  <Accordion title="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).

    ```bash theme={null}
    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                                                                                                             |
    | `--report <format>`          | With a batch `--wait` (`--all` or several `test-ids...`): write a JUnit XML sidecar after polling. Only `junit` is accepted. |
    | `--report-file <path>`       | Output path for `--report` (required when `--report` is set; written atomically)                                             |
    | `--report-suite-name <name>` | Override the JUnit `<testsuite name="...">` (default `testsprite:<projectId>`)                                               |

    <Info>
      Auto-heal is on by default and uses a small amount of credit only when it actually repairs a step — see [Rerun & Auto-Heal](/cli/core/rerun-and-auto-heal#auto-heal).
    </Info>
  </Accordion>

  <Accordion title="test flaky — replay N times and score stability">
    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."

    ```bash theme={null}
    testsprite test flaky <test-id> [options]
    ```

    | Flag            | Description                                           |
    | :-------------- | :---------------------------------------------------- |
    | `--runs <n>`    | Number of replays (1–10, default 5)                   |
    | `--until-fail`  | Stop at the first non-passing attempt                 |
    | `--timeout <s>` | Per-attempt max seconds to wait (1–3600, default 600) |

    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.

    ```bash theme={null}
    testsprite test flaky test_3a9f21c7 --runs 8 --output json
    ```

    <Note>
      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.
    </Note>
  </Accordion>

  <Accordion title="test code — get / put">
    **test code get `<test-id>`** — print the generated test code to stdout, or write to a file.

    ```bash theme={null}
    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.

    ```bash theme={null}
    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 <python>`       | No       | Set the stored code language. Only `python` is accepted — TestSprite executes all test code as Python. Defaults to the existing language.               |
    | `--idempotency-key <token>` | No       | For safe retries                                                                                                                                        |
  </Accordion>

  <Accordion title="test plan put — replace FE test steps">
    Replace a frontend test's `planSteps[]`. Returns 400 for backend tests — use `test code put` instead.

    ```bash theme={null}
    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                                                       |
  </Accordion>

  <Accordion title="test failure — get / summary">
    **test failure get `<test-id>`** — write a self-contained failure-context bundle for the latest failing run.

    ```bash theme={null}
    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.

    ```bash theme={null}
    testsprite test failure summary <test-id>
    ```

    JSON: `{ testId, status, failureKind, snapshotId, rootCauseHypothesis, recommendedFixTarget }`.
  </Accordion>

  <Accordion title="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.

    ```bash theme={null}
    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).
  </Accordion>

  <Accordion title="agent — install / list / status">
    **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.

    ```bash theme={null}
    testsprite agent install [options]
    ```

    | Flag             | Description                                                                                                                                                                                              |
    | :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `--target <t>`   | Agent target (repeatable/comma-separated; prompts if TTY, else defaults to `claude` with an `[info]` line on stderr): `claude`, `cursor`, `cline`, `antigravity`, `kiro`, `windsurf`, `copilot`, `codex` |
    | `--skill <name>` | Skill to install (repeatable/comma-separated): `testsprite-verify`, `testsprite-onboard`. Default: both                                                                                                  |
    | `--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/{skill}/SKILL.md`              |
    | `antigravity` | experimental | own-file        | `.agents/skills/{skill}/SKILL.md`              |
    | `cursor`      | experimental | own-file        | `.cursor/rules/{skill}.mdc`                    |
    | `cline`       | experimental | own-file        | `.clinerules/{skill}.md`                       |
    | `kiro`        | experimental | own-file        | `.kiro/skills/{skill}/SKILL.md`                |
    | `windsurf`    | experimental | own-file        | `.windsurf/rules/{skill}.md`                   |
    | `copilot`     | experimental | own-file        | `.github/instructions/{skill}.instructions.md` |
    | `codex`       | experimental | managed-section | `AGENTS.md`                                    |

    `{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`.

    ```bash theme={null}
    testsprite agent list
    ```

    ***

    **agent status** — check installed skill files against what this CLI version would install. Pure local, no network.

    ```bash theme={null}
    testsprite agent status [options]
    ```

    | Flag           | Description                            |
    | :------------- | :------------------------------------- |
    | `--dir <path>` | Project root to inspect (default: cwd) |

    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.
  </Accordion>

  <Accordion title="usage — credit balance and plan info">
    Show your account and plan info. Credit fields (`credits`, `subPlan`, `creditsPerRun`) appear when the backend supplies them.

    ```bash theme={null}
    testsprite usage
    ```

    Alias: `testsprite credits`. Calls `GET /me`.
  </Accordion>
</AccordionGroup>

## Where to Go Next

<Columns cols={2}>
  <Card title="Configuration" href="/cli/reference/configuration" icon="gear">
    Credentials file, profiles, environment variables, and the JSON output contract
  </Card>

  <Card title="Exit Codes & Errors" href="/cli/reference/exit-codes" icon="list-ol">
    Every exit code, error code, and status value in one table
  </Card>

  <Card title="Creating Tests" href="/cli/core/creating-tests" icon="file-circle-plus">
    How to author frontend and backend tests from the CLI
  </Card>

  <Card title="Running Tests" href="/cli/core/running-tests" icon="play">
    Triggering runs, polling, and pulling failure bundles
  </Card>
</Columns>