Skip to main content
The CLI resolves credentials and settings from three sources in priority order: environment variables, the credentials file (~/.testsprite/credentials), and built-in defaults. Per-invocation flags override everything else.

​
Global flags

Global flags override both environment variables and the credentials file for a single invocation. They must appear before the subcommand. Full descriptions are in the Command Reference.

​
Credentials file

The CLI stores API keys in ~/.testsprite/credentials, an INI-style file. The directory is created with mode 0700 and the file with mode 0600. Writes are atomic — a partial write never corrupts an existing key.
Sample file:
Run testsprite setup to write a profile interactively. Use --from-env in CI to skip the prompt.

​
Profiles

A profile is a named section in the credentials file. Each profile holds an api_key. You can maintain as many profiles as you like — for example, one for interactive use and one with a separate API key for CI. There’s no separate “select profile” command — you apply a profile to whichever command you run. For a single command, prepend the global --profile flag (here project list is just an example command):
To use a profile for the rest of a shell session, set the environment variable so every command picks it up:
The active profile defaults to default if neither --profile nor TESTSPRITE_PROFILE is set.

​
Environment variables

Environment variables override the credentials file but are overridden by their corresponding flag.
In CI, set TESTSPRITE_API_KEY in your secrets store and pass --from-env to testsprite setup. The CLI never logs the key value.

​
Resolution precedence

The CLI resolves each setting through a fixed chain. First match wins. Profile selection:
  1. --profile flag
  2. TESTSPRITE_PROFILE environment variable
  3. Literal "default"
API key:
  1. TESTSPRITE_API_KEY environment variable
  2. api_key in the active profile from ~/.testsprite/credentials

​
The JSON output contract

--output json is the stable, parseable contract every command supports, and exit codes are stable independently of output mode — so agents and CI scripts branch on the exit code rather than parsing stderr. See Output & Scripting. On error, every command emits a consistent JSON envelope regardless of --output mode; for its shape and the full error-code table see Exit Codes & Errors.

​
Request timeouts

--request-timeout <seconds> sets the client-side timeout for each individual HTTP request (range 1–600, default 120). Set it via the environment variable as milliseconds: TESTSPRITE_REQUEST_TIMEOUT_MS=30000. This timeout governs single HTTP round-trips only. It does not affect the --timeout ceiling on test run --wait, test wait, or test rerun --wait — those polling loops run until the run reaches a terminal status or the wait timeout expires, independent of per-request timeouts. When a run completes — and on test create / test create-batch — the JSON output includes an optional dashboardUrl field and text mode prints a Dashboard: line when the link is available. It deep-links directly into the Web Portal view for that test. The backend builds the link when it can (it knows things the CLI cannot, like the correct portal origin and route for your account); when the backend offers no link, the CLI falls back to computing one from projectId + testId where both are known. The field is not guaranteed on every completion: when the backend reports that no correct link exists, the CLI prints no URL at all (with an [advisory] pointing at test get <id>) rather than a link that would 404.
The dashboardUrl field is absent under --dry-run.

​
Where to Go Next

Authentication

Configure API keys, profiles, and non-interactive CI auth

Command Reference

Every command, flag, and output shape

Exit Codes & Errors

Every exit code and error code in one table

CI/CD Integration

Use the CLI in GitHub Actions and other pipelines