CLI commands
teststream <command> [options]. The CLI is the npm package teststream: install it with npm install -g teststream, or run any command with npx teststream <command>. In CI use npx --yes teststream@1 <command>, which pins the major version. See Set up the CLI.
Commands that work on a project take --project <slug> or use TESTSTREAM_PROJECT. Run-specific commands take a run ID, not a run URL or test key; without one, status, report, cancel, diagnose and propose-fixes print their usage and exit 2.
Settings
| Variable | Meaning |
|---|---|
TESTSTREAM_URL | The server's API base URL, including /api, without /v1. Defaults to the hosted Teststream, https://api.teststream.ai/api. Set it only for a self-hosted server (for example https://teststream.example.com/api) or local development (http://localhost:3100/api). |
TESTSTREAM_API_KEY | A Teststream organization API key (Organization > Keys > Teststream API keys); it acts for the whole organization. Required for API calls, not for help, --version or installing skills. |
TESTSTREAM_PROJECT | Default project slug, used when --project is not given. |
Requires Node.js 22 or newer. The CLI appends /v1 to TESTSTREAM_URL and does not load .env files. It sends the key in x-teststream-api-key; TESTSTREAM_PROJECT does not limit the key's organization access.
Command map
| Goal | Command |
|---|---|
| Start tests and optionally wait | run |
| Read a result or Markdown report | status, report |
| Stop execution | cancel |
| Explain failures; draft test changes | diagnose, propose-fixes |
| Read, validate or propose test source | tests list, tests get, tests validate, tests push |
| Inspect reusable steps | shared-steps list, shared-steps get |
| Connect a coding agent | skills, mcp |
| Show the command list, one command's options, or the version | help, help <command>, <command> --help, --version |
Help and version
| Command | Prints |
|---|---|
teststream help (or --help, or no command) | The commands, the settings and the exit codes. |
teststream help <command>, teststream <command> --help | That command's usage and options, for example teststream help run. |
teststream --version | The CLI's version. |
These do not need an API key or contact the server.
teststream run
Starts a run.
teststream run --project <slug> [selection] [target] [wait] [merge request]
| Option | Meaning |
|---|---|
--project <slug> | Project to run. Overrides TESTSTREAM_PROJECT. |
--tests KEY1,KEY2 | Run these test keys. Explicit keys bypass --affected selection. |
--tag <tag> | Run tests with this tag. |
--folder <folder> | Run tests whose folder starts with this value. |
--env <name> | Environment name, matched case-insensitively. Defaults to the project's oldest environment. |
--base-url <url> | Override the environment's base URL. |
--branch <name> | Use an existing Teststream branch/change set. Does not deploy code. Without it, an MR/PR run uses its detected source branch; a plain CLI run uses main. |
--name <text> | Name the run. |
--wait | Wait for the run to finish, print the summary, and return an exit code. |
--timeout <time> | With --wait: polling duration. 90s, 20m, 1h; a bare integer means minutes. Default 30m. Any other value is an error (exit 2) and no run starts. Does not cancel the run. |
--fail-on-heal | With --wait: return 1 for a healed pass. Does not change server verdicts, provider status or healing settings. |
--diagnose | With --wait, when a finished run produces exit code 1: request and print diagnosis. Rule-based diagnosis is model-free; other cases can incur AI cost. |
--propose-fixes | With --wait, after a finished run with failed/blocked tests: draft test updates on its open branch. Can incur AI cost. |
--mr auto|<number>|<link> | Report to a pull or merge request. auto reads the CI environment. |
--affected | With --mr: use app-map/test-name heuristics and critical tags. Falls back to the available candidates when unsure; tag/folder filters still apply. |
--repo <repo>, --provider github|gitlab, --sha <commit> | Override what --mr detected. |
--json | Print the run as JSON. |
Without --wait, a successful start prints the run link (or JSON) and exits 0; this is not a passing test result. It does not run the diagnosis/fix follow-ups. With --wait, polling occurs every five seconds. A status check that fails with a network error or a server error (5xx) is retried for about a minute, so a short outage or a server restart does not end the wait; if the server is still unreachable after that, the CLI gives up with exit 2 (the run itself continues on the server).
Unlike tests push and MCP tools, a plain run does not infer a test branch from your current git checkout. Use --branch or --mr.
With --mr, mergeRequestError can report a provider notification failure even when test execution succeeds. The test-result exit code does not enforce successful reporting.
teststream status <run>
Prints a run's summary: counts, estimated cost, non-passing items with available notes, healed passes and the run URL. Accepts --json and --fail-on-heal. Returns the same result codes as run --wait, including 3 if the run is still unfinished; it does not wait.
teststream report <run>
Prints a Markdown report of the run. It returns 0 when retrieval succeeds even if the report describes failed tests. Use status to evaluate the verdict.
teststream cancel <run>
Requests cancellation and prints the summary. Returns 0 for a successful request, not the run's test-result code. It does not accept a run URL.
teststream diagnose <run>
Diagnoses eligible failed/error test items using rules or AI. Does not execute tests or modify their source. Accepts --json; results include diagnosed and costUsd. Check per-item error fields: a successful command can contain unsuccessful individual diagnoses.
teststream propose-fixes <run>
Drafts updated tests on the run's open branch for review; may incur AI cost. A run without branch context cannot use this command. Accepts --json; results include branch, proposed, skipped and costUsd.
This does not edit application code, run the proposals, accept/merge them or change the failed run. An empty proposed array is possible even with exit 0; inspect skipped reasons.
teststream tests
| Command | Meaning |
|---|---|
tests list [--q <text>] [--tag <tag>] [--folder <folder>] [--json] | List tests: key, status if not active, name, folder. |
tests get <KEY> | Print a test's source. |
tests validate <file> | Check a file like a save does. Prints problems with line numbers. Warnings (for example about logging in) do not fail. |
tests push <file> [--branch <name>] [--folder <folder>] | Propose the file on a branch. It waits for review. Without --branch the current git branch is used. |
tests push <file> --main | Save directly on main. |
All these commands require a project and API access, including validation. push validates before writing, and warnings alone do not fail it. Keep key in the source to update an existing test; omit it to create a new one. A new direct-main save creates a draft, not automatically an active test.
tests push refuses to infer a target on main, master, trunk, develop, or an unknown/detached branch: pass a feature --branch or explicitly choose --main. Avoid combining those options; --branch takes precedence.
teststream shared-steps
| Command | Meaning |
|---|---|
shared-steps list [--json] | The project's shared steps: name, parameters, description. |
shared-steps get <name> | Prints one shared step's source. Quote a name with spaces: shared-steps get "log in". |
Shared steps are made on the Shared steps screen. Use them in tests with use:.
teststream mcp
Starts an MCP server over stdio for coding agents. Set --project or TESTSTREAM_PROJECT, and provide the key (and, for a self-hosted server, the URL) to that process. Agents start it with npx -y teststream mcp. It does not serve HTTP. Start it with the application's checkout as its working directory for branch inference. See MCP setup.
teststream skills
Copies Teststream's skills into a repository for coding agents.
| Option | Meaning |
|---|---|
--target a,b | Any of claude-code, cursor, codex, copilot, opencode. Default claude-code. |
--all | Every target. |
--dir <path> | Repository to write to. Default: the current directory. |
--all takes precedence over --target. The command overwrites installed Teststream skill files and replaces its managed instruction block; it does not register an MCP server or contact the API.
Output formats
--json is implemented for run, status, diagnose, propose-fixes, tests list and shared-steps list. Other commands still print source or human-readable output even if that flag is supplied.
For a run/status JSON snapshot:
| Field | Meaning |
|---|---|
id, url | Run identifier for follow-up commands and web link. |
status, done | Run lifecycle state and whether it has ended. |
environment, branch | Chosen environment and Teststream change-set key, if any. |
counts | Totals including passed, healed, failed, blocked, error and skipped items. |
items | Per-test results, verdict/mode, failure details and stored diagnoses when available. |
costUsd | Estimated run cost. |
mergeRequest, mergeRequestError | Linked request metadata and any reporting error. |
selection | Affected-test selection details, including a human-readable reason. |
run --json --diagnose and run --json --propose-fixes append plain-text follow-up output. Use separate commands when saving one valid JSON document per artifact. Errors are written to stderr; a pre-run error can leave stdout empty.
Exit codes
For run --wait and status:
| Code | Meaning |
|---|---|
| 0 | Every test passed. |
| 1 | A test failed, was blocked, could not run or was skipped. Also: a test needed a heal and --fail-on-heal was set. |
| 2 | The run could not start, failed as a whole, was cancelled, or had no tests. Also used for command errors and bad usage, and when run --wait could not reach the server for about a minute. |
| 3 | The run is unfinished: run --wait exhausted its polling window, or status observed it still running. |
tests validate and tests push return 1 for validation problems, 0 for success, and 2 for command/API errors. Other successful commands return 0 regardless of the test verdict. Diagnosis/proposal results can contain individual errors/skips with exit 0.
Branch and environment selection
| Entry point | Default test branch |
|---|---|
CLI run without --mr or --branch | Main, regardless of the local git branch. |
CLI run --mr auto | Source branch from the CI event; opens/reuses its change set. |
CLI tests push | Current feature branch; otherwise explicit target required. |
MCP tests_propose | Current feature branch, or explicit branch; main is refused. |
MCP tests_run / session_start | Current feature branch when available; may use main when no proposals exist. Read the returned note. |
The project/environment determines the application URL and credentials. Branch selection changes test versions, not those environment settings. Use --base-url to point a run at an already-deployed preview.
MCP tools
| Tool | For |
|---|---|
tests_search, tests_get | Find and read tests. |
tests_validate | Check test text like a save does. |
tests_draft | AI draft of a test from a goal (paid). |
tests_propose | Propose a new test, an edit or an archive on the branch. |
shared_steps_list | The project's shared steps. |
session_start, session_step, session_run_to, session_run_all, session_keep, session_close | Run a test step by step in a browser, and keep what passed. |
tests_run, runs_get, runs_list, run_item | Run tests and read runs and one test's steps and screenshots. |
runs_diagnose, runs_propose_fixes | Diagnose a run's failures and draft test updates (paid). |
knowledge_search | The app's words, accounts and never-do rules. |
test_ids | The attribute tests find elements by (Settings → Test id attribute) and the recorded steps that still find an element by its text. |
changeset_status | The branch's proposals and whether they are verified. |
MCP tools use structured arguments rather than CLI flags. Common arguments are key for tests_get, source for validation, reason plus source/test for a proposal, id for runs_get, and run plus test for run_item. Session tools return the session ID used by later calls.
tests_run with wait: true waits up to ten minutes, not the CLI's thirty-minute default. Inspect done and continue with runs_get if needed. Verification sessions require session_keep after all steps pass and session_close when finished.