TestRelic CLI authentication

The CLI signs in with a TestRelic personal access token (PAT, tr_mcp_…), the same kind @testrelic/mcp uses. There are two ways to get one onto a machine:

Either way, the token is saved to ~/.testrelic/token, written with owner-only (0600) file permissions.

Browser sign-in

testrelic login

The CLI prints a link and a confirmation code, and opens the link in your browser. Approve the request there, signed in to TestRelic, and the CLI saves its token and prints Logged in as <email> @ <organization>. On a machine without a browser, such as over SSH, open the link on any device. The code is short-lived: if the window closes before you approve, run testrelic login again for a fresh one.

The token is listed under Settings → MCP Tokens as TestRelic CLI (<host name>). Signing in again from the same computer replaces that token instead of adding another.

Studio signs in separately. TestRelic Studio keeps its own token in ~/.testrelic/studio-token, listed as TestRelic Studio (<host name>), so signing in to Studio doesn't replace the CLI's token, and the other way round. A token Studio created before it had its own name can still be listed as TestRelic CLI (<host name>) until Studio next signs in.

The 10-token limit

Each user can hold 10 live MCP tokens; expired tokens don't count. When a Studio or CLI sign-in would go over the limit, TestRelic revokes the least recently used token that Studio, the CLI or onboarding created for a machine, and that machine has to sign in again. Tokens you created and named yourself under Settings → MCP Tokens are never revoked. If only those are left, the sign-in is refused with "Maximum of 10 MCP tokens per user reached. Revoke one under Settings → MCP Tokens, then sign in again."

Token login

testrelic login --token tr_mcp_xxxxxxxx

In the interactive CLI, /login token tr_mcp_… does the same. The CLI checks the token and prints the account it belongs to.

TESTRELIC_MCP_TOKEN is honored as a lowest-precedence fallback: a saved login always takes priority over the environment variable.

export TESTRELIC_MCP_TOKEN=tr_mcp_xxxxxxxx   # fallback only

Which credential a run uses

A one-shot run (testrelic -p "…") uses the first of these it finds:

1. --token tr_mcp_…, or the TRC_TOKEN environment variable, which has exactly the same precedence. A token on a command line shows up in local process listings and an environment variable doesn't, which is why Studio passes its token this way. The CLI removes TRC_TOKEN from its environment once it has read it, so nothing it starts (MCP servers, shells, test runs) inherits it.
2. --session, which forces the saved session cookies even when a token is available.
3. The saved token in ~/.testrelic/token.
4. Saved session cookies in ~/.testrelic/cookies.json.
5. TESTRELIC_MCP_TOKEN.

If TestRelic refuses that credential, the run tries the others in the same order, then Studio's token, and says which one it's trying next. A refused --token or TRC_TOKEN is the exception: the run moves on only to Studio's token, never to your saved CLI credentials. If every one is refused, the error lists each credential by name with the server's reason. The interactive CLI checks the session cookies before the saved token.

Log out

testrelic logout          # clear the saved session cookies
testrelic logout --all    # also delete the saved token (~/.testrelic/token)

A browser sign-in saves a token, so use --all to sign a computer out completely. In the interactive CLI, /logout confirm clears both. If TESTRELIC_MCP_TOKEN is set, the CLI keeps signing in with it, and logout tells you how to unset it.

Pointing at a different backend

The CLI defaults to production. Point it elsewhere for staging or self-hosted setups:

testrelic config set baseUrl https://your-host.example.com/api/v1   # persisted
testrelic --base-url https://your-host.example.com/api/v1           # per-invocation
export TESTRELIC_CLOUD_URL=https://your-host.example.com/api/v1     # environment

Diagnostics

In the interactive CLI, /doctor checks your configuration, sign-in, MCP servers and terminal.

Next steps

→ Quickstart · Configuration