Quickstart

This walks you from a fresh install to your first answer in a couple of minutes. If you have not installed yet, see Installation.

Onboard (optional)

If you're wiring up a project for the first time, two commands get you set up:

# deterministic, keys-only — wires local config for the SDKs
testrelic setup --api-key tr_live_xxxxxxxx --mcp-token tr_mcp_xxxxxxxx

# agentic onboarding that inspects your project and detects the framework
testrelic init --framework playwright

setup takes your keys and writes local config (add --no-install to skip installing the SDK). init is the agentic path — pass --yes to accept defaults or --no-upload to configure without sending a run. Already set up? Skip straight to logging in.

1. Log in

testrelic login

This uses the encrypted email/password challenge flow; your session persists in ~/.testrelic/cookies.json and auto-refreshes. Prefer a token for headless use — see Authentication.

2. Ask your first question

Launch the interactive UI and type a question:

testrelic

❯ why did the nightly regress?
⏺ query_runs(suite: "nightly", window: "7d")
⎿ 142 runs · 3 newly failing
The nightly suite dropped to 94.2% pass rate after deploy #4891 …

Answers stream as markdown, tool calls show inline, and any artifact the agent produces (dashboards, reports, test plans) renders directly in your scrollback.

3. Add context

• Press @ to attach a repo, run, branch, test case, environment, suite, or tag as a context chip, fed from your org's data.
• Press ! to run a local shell command; its output is attached to your next message.

❯ @checkout-repo @run:4891 summarize the new failures

4. Useful basics

• Type / to open the slash-command menu (/artifacts, /resume, /export, /help, …). See Slash commands.
• Press Ctrl+R to reverse-search your input history (persistent across sessions).
• Press Esc to interrupt a streaming turn.

5. Print mode (scripts and CI)

For one-shot, pipe-friendly answers, use -p:

testrelic -p "which suite has the highest flake rate?"
tr -p "list newly failing tests on main" --output-format json

Artifacts render as ANSI on a terminal and as plain text when piped. See Artifacts & headless output for the output formats.

Next steps

• Authentication — session vs personal access token.
• Modes & engines — Cloud vs Local, and which backend runs a turn.
• MCP host — let the agent call your local tools.
• Configuration — base URL, themes, keybindings.