Reqly - From route to CI test in one agent session.

Your agent reads your codebase, builds the collection, writes the assertions, exports the GitHub Actions workflow, and ships it to CI. You never touch it.

npm install -g getreqly
reqly setup

Works with: Cursor · Claude Code · Gemini CLI · VS Code (Claude extension)

The full zero-human pipeline

/goal Read my Express routes, build a collection with assertions, write an
e2e flow for login → checkout, and export it to CI - don't stop until it's green.

1. "Read my Express routes and build a collection with assertions"
        → agent calls create_collection + create_request for every endpoint

2. "Write an e2e flow for the login → checkout path"
        → agent calls create_flow + add_flow_step, runs it, all green

3. "Export it to CI"
        → agent calls export_flow_ci
        → .github/workflows/checkout-flow.yml written automatically
        → installs Reqly, runs the flow, uploads JUnit results as a build artifact

In Claude Code, /goal keeps the agent working the whole pipeline in one session instead of re-prompting at every step - Reqly's MCP tools are built to be chained that way.

No bru run wiring. No manual Actions YAML. No environment setup. One agent session, tests running in CI forever.

Reqly runs locally as a background service with two interfaces from the same engine:

• MCP server (stdio) - your agent connects once and gets the full toolkit. Zero UI, zero LLM cost on our side.

• Localhost web UI - open localhost:4242 to browse collections, watch your agent work, fire requests manually.

Collections are plain YAML in .reqly/ in your repo. Git-native, human-readable, directly writable by agents.

Table of Contents

• Installation

• How It Works

• MCP Tools

• CLI Runner

• Flows

• Mock Server

• Capture Inbound Requests

• Collections and Assertions

• Why Reqly

• Recently Shipped

• FAQ

• Star History

Related MCP server: EvalView

Why Reqly beats Postman, Insomnia, and Bruno for AI-native developers

Collections are plain YAML in your repo. Every other tool stores collections in a proprietary format or database (Insomnia uses NeDB binary files, Postman locks them behind a cloud account). Reqly's .reqly/ folder travels with your code via git - readable, diffable, committable. AI agents can read and write collection files directly without any tool calls.

Reqly is an MCP server, not an MCP client. Insomnia recently added an MCP client so it can call external tools. Reqly goes further: it is the MCP server. Your AI agent in Cursor or Claude Code connects once and gets a full set of tools to fire requests, chain responses, run collections, and verify assertions - no UI required, no extra configuration. The desktop UI (coming soon) is a shell around the same headless engine - the MCP connection stays alive whether the window is open or closed. Other tools built GUI-first have to extract a headless runtime as an afterthought; Reqly was headless from day one.

Auto-capture, zero manual work. Reqly can capture outbound traffic from your dev server via a proxy (reqly exec npm run dev), inbound traffic via a one-line middleware, and inbound webhooks via a public tunnel - then save everything into collections automatically. No other tool does all three.

BYOK, no cloud dependency. There is no Reqly cloud. Collections stay in your repo. Secrets stay in ~/.reqly/config.json on your machine. The prompt bar in the UI uses your own API key. Nothing is sent to Reqly's servers - because there are no Reqly servers. No account required, no telemetry, no sync.

What an agent session looks like

1. "Read my routes and build a collection" → agent calls create_collection + create_request for each endpoint
2. "Run the collection and check for failures" → agent calls run_collection, assertions pass/fail
3. "Write an e2e flow for the login → checkout path" → agent calls create_flow + add_flow_step, runs it

Installation

Reqly runs on macOS, Linux, and Windows.

# On any platform via npm
npm install -g getreqly

# On macOS via Homebrew (CLI only)
brew tap RutvikPansare/reqly
brew install reqly

# On macOS via Homebrew (Desktop App + CLI)
brew install --cask reqly

Then wire it up to your AI tool:

reqly setup

This configures Cursor, Claude Desktop, Claude Code, Gemini CLI, and Codex in one shot. To configure a specific tool only: reqly setup cursor, reqly setup claude, reqly setup gemini.

Restart your AI tool, then ask it: "list my Reqly collections".

Try it in 30 seconds

No API, no agent setup needed yet. Run this in any directory:

reqly init
reqly start

Open localhost:4242 - you'll have a working collection against JSONPlaceholder with request chaining, variables, assertions, and a flow already set up. Then connect your agent and ask it to extend it.

The fastest way to start with your own API

Don't capture traffic, don't write YAML by hand - just tell your agent to read your code:

"Read my Express routes and build a Reqly collection for every endpoint"

The agent reads your codebase and calls create_collection + create_request for each route it finds. No traffic capture needed - it already knows your API from the code.

What your agent can do

Reqly is not an AI - it's an engine for your AI. Connect once, then your agent has the full toolkit.

🗂️ Collections and Requests

🌍 Environments and Variables

🔐 Auth

📋 OpenAPI Contract Validation

🔗 Flows

🕵️ Capture and Proxy

🎭 Mock Server

Recently shipped

• Flows - multi-step automation tests (run, extract, assert, poll, conditional) with data-driven support

• OpenAPI contract validation - point a collection at a spec; every response is checked automatically

• Multipart body editor - send multipart/form-data with file and text parts

• Response diffing - detects what changed between runs: status, latency delta, body diff

• Mock server - serve saved examples as a real HTTP server for frontend dev and agent testing

• Pre/post scripts - per-request sandboxed JS that can read/write env vars before and after the request fires

• GraphQL workspace - dedicated editor with schema introspection, syntax highlighting, and variable panel

• cURL import - paste any cURL command; fields populate instantly

• TypeScript interface generator - infers a typed TS interface from any JSON response body

• .env integration - zero-config: if .env exists at the project root it's loaded automatically

Flows

Flows are multi-step sequences your agent builds once and CI runs forever. Each step chains into the next - extract a value from one response and inject it into the next request automatically.

flowchart LR
    A(["▶ run\nFire a request"]) --> B(["⬇ extract\nPull value from response"])
    B --> C(["✓ assert\nCheck the response"])
    C --> D{"⎇ conditional\nBranch on result"}
    D -->|"pass"| E(["▶ run\nNext request"])
    D -->|"retry"| F(["↻ poll\nRepeat until condition met"])
    F --> E

    style A fill:#1e3a5f,stroke:#3b82f6,color:#e2e8f0
    style B fill:#1e3a5f,stroke:#3b82f6,color:#e2e8f0
    style C fill:#14532d,stroke:#22c55e,color:#e2e8f0
    style D fill:#3b1f1f,stroke:#ef4444,color:#e2e8f0
    style E fill:#1e3a5f,stroke:#3b82f6,color:#e2e8f0
    style F fill:#3b2f0a,stroke:#f59e0b,color:#e2e8f0

Example: login → create post → verify it exists

# .reqly/flows/e2e-post.yaml
steps:
  - type: run
    request: auth/login

  - type: extract
    from: response.body.token
    into: authToken          # now available as {{authToken}}

  - type: run
    request: posts/create-post

  - type: extract
    from: response.body.id
    into: postId

  - type: assert
    field: status
    operator: eq
    value: 201

  - type: run
    request: posts/get-post  # uses {{postId}} in the URL

  - type: assert
    field: body
    path: post.title
    operator: eq
    value: "Hello world"

Run it:

reqly run-flow "e2e-post"
reqly run-flow "e2e-post" --reporter json
reqly run-flow "e2e-post" --data-row '{"userId":"42"}'

Export to CI in one command:

reqly export-flow "e2e-post" --format github-actions
# Writes .github/workflows/e2e-post.yml - installs Reqly, runs the flow, uploads JUnit results

Agents can do the same via the export_flow_ci MCP tool - no manual YAML writing.

Capture Inbound Requests (Middleware)

If your codebase is too complex or undocumented for the AI-writes-collection workflow, install reqly-middleware to capture every request coming into your app automatically:

npm install reqly-middleware

// Express
import { reqlyMiddleware } from 'reqly-middleware'
app.use(reqlyMiddleware())

// Next.js (middleware.ts at project root)
import { reqlyNextMiddleware } from 'reqly-middleware/next'
export default reqlyNextMiddleware()

// Fastify
import { reqlyMiddlewareHook } from 'reqly-middleware'
fastify.addHook('onRequest', reqlyMiddlewareHook())

Restart your dev server and Reqly starts capturing inbound requests into the Captured collection. Local development only - it phones home to localhost:4242 and has no effect in production. Ask your agent to call install_middleware to get the exact snippet for your framework.

How collections work

Collections live in .reqly/ inside your project directory as human-readable YAML files. They support variables, authentication profiles, and test assertions.

Example request YAML:

name: create-user
method: POST
url: "{{baseUrl}}/api/users"
headers:
  Content-Type: application/json
body:
  email: test@example.com
assertions:
  - field: status
    operator: eq
    value: 201
  - field: body
    path: user.id
    operator: neq
    value: ""

Assertions

Assertions run automatically after every request execution. Each assertion checks one thing:

Common mistake: writing type: "status" instead of field: "status" - this silently produces an assertion that never matches, always failing with "got undefined".

Examples:

assertions:
  - field: status       # HTTP status code
    operator: eq
    value: 200

  - field: body         # JSON body field at path
    path: user.active
    operator: eq
    value: true

  - field: latency      # response time in ms
    operator: lt
    value: 2000

CLI Runner

You can use Reqly in your terminal or CI/CD pipelines to run test suites.

reqly run users

Supports reporter formats and environments:

reqly run users --env prod --reporter json
reqly run users --reporter tap
reqly run users --reporter junit > results.xml

--reporter junit writes a standard JUnit XML <testsuite>/<testcase> document to stdout - redirect it to a file for your CI to pick up. Each assertion on a request becomes one <testcase>; a request with no assertions is one implicit testcase that fails only if its status is >= 500.

Running Flows

reqly run-flow "Login Flow"
reqly run-flow "Login Flow" --reporter json
reqly run-flow "Login Flow" --reporter tap
reqly run-flow "Login Flow" --reporter junit > results.xml
reqly run-flow "Signup Flow" --data-row '{"email":"test@example.com"}'

Exporting flows to CI

reqly export-flow "Login Flow" --format github-actions

Writes .github/workflows/Login Flow.yml (creates the directory if needed) that installs Reqly, starts it, runs the flow with --reporter junit > results.xml, and uploads results.xml as a build artifact on push and pull request. Add a "Start server" step before "Run flow" if the flow hits a local API.

Want your agent to re-check the API on a cadence instead of only on push? In Claude Code:

/schedule every morning at 9am, run reqly run-flow "Login Flow" --reporter junit and tell me if anything broke

Mock server

Serve saved example responses as a real HTTP server so frontend code or agents can make calls against controlled responses without a live backend:

reqly mock <collection>           # default port 4243
reqly mock <collection> --port 5000

On start, Reqly prints a table of all active routes (method, path, example count). Press Ctrl+C to stop.

To select a specific example per request, set the X-Reqly-Example: <name> header. Without it, the first saved example is served.

The mock server also exposes REST routes on the main server (port 4242) for UI and programmatic control:

POST /api/mock/start   { collection, port? }
POST /api/mock/stop
GET  /api/mock/status

FAQ

1. Collections are YAML files in your repo, not locked in a cloud account or proprietary binary format. They travel with your code via git, your agent can read and write them directly, and you can diff them in a PR.

2. Reqly is an MCP server. Your AI agent connects to it and gets a full toolkit - fire requests, run flows, validate contracts - without opening a UI. Postman and Insomnia are UI-first; Reqly is agent-first.

3. No cloud dependency, ever. No account required, no sync, no telemetry. Everything runs on your machine.

1. Cursor / most editors - run reqly setup cursor again from inside your project directory. The setup command writes ${workspaceFolder} into the MCP config so Cursor passes the right path at launch.

2. Claude Desktop - run reqly use /path/to/your/project to set the active project globally, then restart Claude Desktop.

3. Manual override - set the REQLY_PROJECT_DIR environment variable on the MCP server entry in your AI tool's config.

reqly run my-collection --reporter junit > results.xml

Or generate the full GitHub Actions workflow automatically:

reqly export-flow "my-flow" --format github-actions

reqly import postman-collection.json
reqly import bruno-collection/

Or via the MCP tool: your agent can call import_collection and pass the file path. Reqly also exports to Postman v2.1 and OpenAPI 3.0 if you need to go the other way.

1. .env files - auto-loaded from your project root (or configured via set_dotenv_files)

2. Environment variables - named sets like dev, staging, prod, stored in .reqly/environments.yaml

3. Collection variables - scoped to a single collection, useful for values like baseUrl

Use {{varName}} anywhere in a URL, header, or body. Switch environments with reqly run --env prod or via the UI dropdown.

reqly start --port 4243

Or set it in your MCP config args. The UI will open on whichever port you choose.

// preScript - set a dynamic header before the request
reqly.setEnvVar('timestamp', Date.now().toString())

// postScript - extract a value from the response into an env var
const token = reqly.response.body.access_token
reqly.setEnvVar('authToken', token)

// You can also use reqly.setVar(key, val) / reqly.getVar(key) to store collection-scoped variables in memory

Scripts run in an isolated context with no filesystem or network access - they can only interact with Reqly's variable store and the response object.

For longer scripts, use preScriptFile / postScriptFile instead - set the value to a path relative to the collection folder (e.g. "scripts/post.js"). Reqly reads the file at run time, so you can edit it without touching the YAML. No JSON escaping required.

// create_request({ postScriptFile: "scripts/post.js", ... })
// then edit .reqly/<collection>/scripts/post.js freely

reqly stop        # stops the running instance
reqly status      # check if an instance is running and which project it's on
reqly app         # opens the running instance's UI in your browser

Or press Ctrl+C in the terminal where Reqly is running. Reqly writes a lock file at ~/.reqly/running.json to track the running instance - reqly stop reads this to find and signal the process.

cd /path/to/other-project
reqly start
# "Switched active project to /path/to/other-project"

The new process hands off to the existing instance and exits. The MCP connection stays alive and immediately sees the new project's collections.

reqly exec --tunnel npm run dev

This starts your dev server with a public HTTPS URL. Any requests hitting that URL are proxied to your local server and saved into the Captured collection automatically.

Star History