Docs

Relay documentation

Relay reads your requirements, checks them on every run, and learns your app. These guides take you from your first request to running Relay in CI and from an AI agent.

Quickstart

Install the desktop app, or the command-line runner for your terminal and CI.

# command line
$ npm i -g relayqa
$ relay init ./my-project

Open the folder in the app (or point the CLI at it). Relay adds collections/ and environments/ and you are ready to send your first request. Everything it creates is plain files you commit.

Your first request

Create a request, pick an environment, and send. Scripts and tests run exactly as they would in a collection, and the response, timing and test results come back together.

Your first flow

Record a browser flow or write one in plain English. Relay drives the browser, and when a selector breaks it proposes a repair you accept or reject.

Core concepts

Workspace — a project folder. Collections, environments, flows and the learned model all live inside it as files.
Requirements — your spec document, read into numbered statements Relay can check.
Checks — rules, decision tables and intents that verify a statement. Relay keeps one only when it holds on a build you trust.
The brain — the model Relay builds of your app: screens, actions, APIs and the links between them.

Requirements & coverage

Point Relay at a requirements document. It turns each sentence into a numbered statement and reports which are checked, which are not, and which are only tested from one side — where a bug would slip through.

$ relay req coverage requirements.md
# 172 of 185 statements checked (93%)
# 7 not checked · 5 need test data · 1 one-sided

Writing the missing checks

Relay can draft checks for what is uncovered, using your own API key, a local model through Ollama (free), or by handing you prompts to paste into any chat. It runs them once on a build you trust and keeps only the ones that hold.

One-sided checks are the quiet killers: a rule tested only one way passes even when the other way is broken. Relay flags them so you can close the gap.

The app map

As tests run, Relay learns your app: every screen, the actions between them, and the APIs behind each one. The map shows what is tested and what is not, and tells you what a change will affect before you ship.

$ relay brain impact --api "POST /api/orders"
$ relay brain pr --since origin/main   # PR-ready summary

It also catches contract drift (a field that changed type or disappeared) and screens that show a different value than the API behind them.

Grid, form & lag checks

Point Relay at a page and it exercises what actually breaks in real apps, then reports it in plain language.

$ relay ui check https://orders.internal/grid

Data grids — sorts every column both ways and checks the order; filters each column and checks no matching row is hidden; verifies the sort icons. Handles pinned columns, grouped headers and column-menu filters.
Required fields — empties each one and checks something on screen marks it (a red border, outline or message), then that the mark clears when filled.
Lag — measures real click and keystroke latency, and flags freezes and janky scrolling.

Run it inside a flow with --checks grid,required,lag and Relay reports only what is new since the approved run — ideal for catching regressions after a component-library upgrade.

Browser flows

Flows are browser tests that heal themselves. Record one, or write it in English; Relay runs it headless or headed, repairs broken locators, and can run only the flows a change affects.

$ relay flow run flows/ --since origin/main
$ relay flow record https://my-app.test -o flows/login.flow.json

Agents: MCP & UTCP

Relay exposes its tools over MCP and UTCP, so your coding agent can drive it safely inside your workspace.

$ relay mcp setup ./my-project   # VS Code, Cursor, Claude
$ relay utcp ./my-project        # HTTP manual at /utcp

Agents get real tools, not guesses:

send_requestrun_collectionrun_flowsrequirements_coverageprobe_apicheck_pagechange_impact

Every path an agent passes is resolved inside the workspace and refused outside it; commands run without a shell; the UTCP server listens on localhost only and needs a token. Destructive tools ask before they run.

CLI & CI

Everything in the app is a command, so Relay runs on every pull request.

$ relay run collection.json -e env.json --junit out.xml
$ relay req coverage requirements.md --json coverage.json
$ relay flow run flows/ --since origin/main --fail-on-flaky
$ relay brain pr --since origin/main --post github

Set RELAY_LICENSE in CI and Relay runs headless, writes JUnit and HTML reports, and comments a risk summary on the PR.

Licensing

Relay is licensed with signed keys that work offline — there is no server to call home to. A key carries the plan and, optionally, the one computer it runs on.

$ relay license activate RELAY-…
$ relay license        # show the current licence and this computer

Free covers personal projects. Pro is a one-time, per-seat licence with a year of updates. Team is a flat licence for a whole company. See pricing.