Skip to main content

Set up the CLI

Connect your terminal to an existing Teststream project without starting a browser run.

Install the CLI​

The CLI is the npm package teststream. You need Node.js 22 or newer. Run it without installing anything:

npx teststream --version
npx teststream help

Or install it once so the teststream command is on your path:

npm install -g teststream
teststream --version

Commands beginning with teststream in these guides assume the global install; with npx, put npx in front of them. teststream help lists the commands, and teststream help <command> or teststream <command> --help prints one command's options.

In CI, use npx --yes teststream@1 <command>. --yes skips npx's install prompt, and @1 pins the major version, so a new major release cannot change your pipeline without you choosing it.

If you are developing Teststream itself, you can run the CLI from your checkout instead: node packages/cli/bin/teststream.mjs <command>.

Configure access​

In the web app, open Organization > Keys > Teststream API keys. Create a key and save the value when it is shown. This is a Teststream organization key: it acts for the whole organization. It is not a Claude credential or GitHub/GitLab token. If you cannot see Keys, ask an organization administrator.

Set the project in the terminal:

export TESTSTREAM_PROJECT="SHOP"

Set TESTSTREAM_API_KEY to the key using your local secret tooling. In CI, store it as a secret/masked variable. Do not commit it in YAML, agent configuration or test files, or print it in job logs.

The CLI talks to the hosted Teststream (https://api.teststream.ai/api) by default. Set TESTSTREAM_URL only for a self-hosted server or local development:

# A self-hosted server
export TESTSTREAM_URL="https://teststream.example.com/api"
# A local development server
export TESTSTREAM_URL="http://localhost:3100/api"

TESTSTREAM_URL is the API base URL, including /api, without /v1. The CLI appends /v1 itself. It is not your application's test URL and not the documentation URL. The CLI does not load a .env file for you.

Verify the connection​

teststream tests list --project SHOP

This reads the test inventory; it does not execute tests or request an AI diagnosis. An empty list means the project has no matching tests. An authentication, URL or project error is printed to stderr and returns exit code 2.

--project overrides TESTSTREAM_PROJECT. Use the project's slug, not its display name. The key belongs to an organization; it must be the organization that owns this project.

Choose an environment before running​

A project needs an environment, a reachable application URL, and any login roles and variables its tests require. Configure these in the web app. Prefer an explicit environment:

teststream run --project SHOP --env Staging --tests SHOP-1 --wait

Run this only when you are ready to execute SHOP-1 against Staging. It may change application data and use paid AI execution.

Without --env, the API chooses the project's oldest environment. --base-url overrides where the browser starts, but does not replace the environment's credentials and other settings.

Continue with CI execution, pull/merge request reporting, or coding-agent setup.