> ## 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.
# Authentication
> Configure an API key, check your active identity, and manage named profiles for multiple accounts or environments.
## 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 setup` — 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:
```bash theme={null}
testsprite setup
```
The full onboarding walkthrough
If you want credentials only — no skill install — add `--no-agent`:
```bash theme={null}
testsprite setup --no-agent
```
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. You are only ever prompted for the API key.
```text theme={null}
TestSprite API key: ********
TestSprite initialized.
profile: default
env: production
email: you@example.com
scopes: read:me, read:projects, read:tests, write:tests, run:tests
agent: skipped (--no-agent)
```
For non-interactive environments (CI, Dockerfiles, scripted setup), pass `--from-env` instead of typing at a prompt:
```bash theme={null}
TESTSPRITE_API_KEY=sk-... testsprite setup --from-env --yes --no-agent
```
**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 status` to confirm which key and profile are active:
```bash theme={null}
testsprite auth status
```
Sample text output:
```text theme={null}
userId usr_1478d468
name Your Name
email you@example.com
keyId key_a1b2c3d4
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:
```bash theme={null}
testsprite auth remove
```
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.
```ini theme={null}
[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 `setup`.
## 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:
```bash theme={null}
testsprite --profile ci setup --no-agent
```
To use a profile for any subsequent command, pass `--profile` as a global flag:
```bash theme={null}
testsprite --profile ci project list
```
Or set the environment variable so every command in the session picks it up automatically:
```bash theme={null}
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.
| Variable | Purpose | Precedence |
| :------------------- | :----------------------------------------- | :----------------------------- |
| `TESTSPRITE_API_KEY` | API key to use for all requests | Wins over the credentials file |
| `TESTSPRITE_PROFILE` | Active 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](/cli/reference/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.
| Scope | Gates |
| :-------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `read:me` | `auth status`, `usage` |
| `read:projects` | `project list`, `project get` |
| `read:tests` | `test list`, `test get`, `test steps`, `test result`, `test code get`, `test failure get`, `test failure summary`, `test artifact get` |
| `write:tests` | `test create`, `test create-batch`, `test update`, `test delete`, `test delete-batch`, `test code put`, `test plan put`, `project create`, `project update` |
| `run:tests` | `test 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 setup` *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.
The Web Portal key management walkthrough
## Where to Go Next
Create and manage the projects your tests live in
Author frontend plans and backend code files
Full flag and environment variable precedence reference
Non-interactive auth patterns for pipelines