Skip to main content

​
Signing in

Before you can run any command that talks to the TestSprite API, you need to store a valid API key. The fastest path is testsprite init — it prompts for the key, verifies it against the server, installs the agent skill into your repo, and prints a unified summary, all in one step: 
testsprite init

Installation

The full onboarding walkthrough
If you want credentials only — no skill install — run: 
testsprite auth configure
The CLI calls GET /me with the key you provide before writing anything to disk. A rejected or malformed key never overwrites a working profile. 
# interactive prompt
? API key: sk-...
Profile "default" configured. Endpoint: https://api.testsprite.com
For non-interactive environments (CI, Dockerfiles, scripted setup), pass --from-env instead of typing at a prompt: 
TESTSPRITE_API_KEY=sk-... testsprite auth configure --from-env
Important: The CLI never accepts an API key as an inline positional argument or flag — that would expose it in shell history and process listings. Use the interactive prompt, --from-env, or the TESTSPRITE_API_KEY environment variable.

​
Checking who you are

Run testsprite auth whoami (alias: testsprite auth status) to confirm which key and profile are active: 
testsprite auth whoami
Sample text output: 
userId    usr_1478d468
name      Your Name
email     you@example.com
keyId     key_a1b2c3d4
endpoint  https://api.testsprite.com
env       production
scopes    read:me, read:projects, read:tests, write:tests, run:tests
If your key is missing write:tests or run:tests, the output appends a note: line listing the gap. For machine-readable output, add --output json.

​
Signing out

To remove credentials for the active profile: 
testsprite auth logout
The credentials entry for the selected profile is deleted from ~/.testsprite/credentials. Other profiles are not touched.

​
Where credentials live

The CLI stores credentials in ~/.testsprite/credentials, an INI-style file. The directory is created with mode 0700 and the file with mode 0600. All writes are atomic. 
[default]
api_key = sk-...

[ci]
api_key = sk-...
Each section is a named profile. The section name matches the profile you activated when you ran auth configure.

​
Profiles

Profiles let you manage multiple accounts or API keys (for example, an interactive key and a CI key) without re-entering credentials each time. To configure a named profile, pass --profile before the subcommand: 
testsprite --profile ci auth configure
To use a profile for any subsequent command, pass --profile as a global flag: 
testsprite --profile ci project list
Or set the environment variable so every command in the session picks it up automatically: 
export TESTSPRITE_PROFILE=ci
testsprite project list
The active profile determines which api_key is read from ~/.testsprite/credentials. If the named section does not exist, the CLI exits with a validation error (exit 5).

​
Environment variables

Environment variables override the credentials file. This is the recommended pattern for CI and container environments.
VariablePurposePrecedence
TESTSPRITE_API_KEYAPI key to use for all requestsWins over the credentials file
TESTSPRITE_PROFILEActive profile name (default: "default")Overridden by --profile
Full resolution order:
  • Profile: --profile flag > TESTSPRITE_PROFILE env > "default"
  • API key: TESTSPRITE_API_KEY env > credentials file value for the active profile
For the complete precedence table including the request-timeout setting, see Configuration.

​
Scopes

API keys carry a list of scopes that gate which operations the CLI can perform. All new keys and grandfathered keys default to the full working set.
ScopeGates
read:meauth whoami, usage
read:projectsproject list, project get
read:teststest list, test get, test steps, test result, test code get, test failure get, test failure summary, test artifact get
write:teststest create, test create-batch, test update, test delete, test delete-batch, test code put, test plan put, project create, project update
run:teststest run, test wait, test rerun
testsprite agent install is a pure-local operation — it only writes files to your project directory and never calls the API, so no scope is required. testsprite init does call the API to verify your key (GET /me) and fetch your identity, but it works with any valid key and needs no write or run scope.
If a command fails with a scope error, the CLI prints the required and granted scopes in both text and JSON modes. You can generate a new key with the needed scopes in the dashboard at Settings → API Keys → Create new key.

API Keys

The Web Portal key management walkthrough

​
Where to Go Next

Projects

Create and manage the projects your tests live in

Creating Tests

Author frontend plans and backend code files

Configuration

Full flag and environment variable precedence reference

CI/CD Integration

Non-interactive auth patterns for pipelines