Content
# Reqly - From route to CI test in one agent session.
[](https://www.npmjs.com/package/getreqly)
[](https://github.com/RutvikPansare/Reqly/blob/main/LICENSE)
[](https://github.com/RutvikPansare/Reqly/actions/workflows/ci.yml)
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.
```bash
npm install -g getreqly
reqly setup
```
<!-- TODO: record demo GIF - agent prompt -> MCP tool fires -> collection appears in sidebar -> run -> response shown -->
**Works with:** [Cursor](https://cursor.com) · [Claude Code](https://claude.com/claude-code) · [Gemini CLI](https://github.com/google-gemini/gemini-cli) · [VS Code](https://code.visualstudio.com) (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](#installation)
- [How It Works](#the-full-zero-human-pipeline)
- [MCP Tools](#what-your-agent-can-do)
- [CLI Runner](#cli-runner)
- [Flows](#flows)
- [Mock Server](#mock-server)
- [Capture Inbound Requests](#capture-inbound-requests-middleware)
- [Collections and Assertions](#how-collections-work)
- [Why Reqly](#why-reqly-beats-postman-insomnia-and-bruno-for-ai-native-developers)
- [Recently Shipped](#recently-shipped)
- [FAQ](#faq)
- [Star History](#star-history)
## 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.
```bash
# On any platform via npm
npm install -g getreqly
# On macOS via Homebrew
brew tap RutvikPansare/reqly
brew install reqly
```
Then wire it up to your AI tool:
```bash
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:
```bash
reqly init
reqly start
```
Open `localhost:4242` - you'll have a working collection against [JSONPlaceholder](https://jsonplaceholder.typicode.com) 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.
| | Capability | What it means |
|---|---|---|
| 🗂️ | **Build collections** | Reads your routes, scaffolds requests, no YAML by hand |
| ⚡ | **Fire and assert** | Runs requests, checks status/body/latency, returns pass/fail per assertion |
| 🔗 | **Chain flows** | Multi-step sequences with extract, poll, and conditional branching |
| 📋 | **Validate contracts** | Point at an OpenAPI spec - every response checked automatically |
| 🎭 | **Serve mocks** | Fake a backend from saved examples, no live server needed |
| 🕵️ | **Capture traffic** | Proxy outbound, middleware for inbound, tunnel for webhooks |
<details>
<summary><strong>View all 30+ MCP tools</strong></summary>
<br>
**🗂️ Collections and Requests**
| Tool | What it does |
|------|-------------|
| `list_collections` | Lists all collections and requests in the project |
| `create_collection` | Scaffolds a new collection |
| `create_request` | Adds a request. Supports `{{variables}}`, assertions, pre/post scripts, auth, multipart bodies |
| `run_request` | Fires a request - returns status, body, headers, latency, assertion results, diff, contract violations |
| `run_collection` | Fires all requests in a collection sequentially |
| `get_response` | Retrieves the last stored response (truncated) |
| `get_response_full` | Retrieves the last untruncated response |
| `export_collection` | Exports as Postman v2.1 or OpenAPI 3.0 JSON |
| `import_collection` | Imports a Postman v2.1 or Bruno collection |
**🌍 Environments and Variables**
| Tool | What it does |
|------|-------------|
| `set_environment` | Changes the active environment |
| `create_environment` | Creates a named environment with variables |
| `set_variable` | Sets a variable on an environment |
| `get_variables` | Lists variables for an environment (with source tags) |
| `delete_variable` | Removes a variable |
| `get_collection_variables` | Lists per-collection variables |
| `set_collection_variable` | Sets a per-collection variable |
| `delete_collection_variable` | Deletes a per-collection variable |
| `set_dotenv_files` | Configures which `.env` files are auto-loaded |
| `get_dotenv_files` | Lists the configured dotenv files |
**🔐 Auth**
| Tool | What it does |
|------|-------------|
| `get_collection_auth` | Gets the default auth config for a collection |
| `set_collection_auth` | Sets Bearer / API Key / Basic / OAuth 2.0 auth for all requests |
| `delete_collection_auth` | Removes collection-level auth |
**📋 OpenAPI Contract Validation**
| Tool | What it does |
|------|-------------|
| `set_collection_spec` | Points a collection at an OpenAPI spec (file path or URL) |
| `get_collection_spec` | Gets the spec config and load status |
| `delete_collection_spec` | Removes the spec from a collection |
| `list_spec_operations` | Lists all operations in the loaded spec |
| `validate_response` | Re-validates the last response without re-firing |
**🔗 Flows**
| Tool | What it does |
|------|-------------|
| `create_flow` | Creates a new flow |
| `get_flow` | Gets a flow's config and steps |
| `list_flows` | Lists all flows |
| `delete_flow` | Deletes a flow |
| `add_flow_step` | Appends a step (run / extract / assert / poll / conditional) |
| `update_flow_step` | Replaces a step in place |
| `delete_flow_step` | Removes a step |
| `run_flow` | Executes a flow and returns per-step results |
| `export_flow_ci` | Generates a GitHub Actions workflow and writes it to `.github/workflows/` |
**🕵️ Capture and Proxy**
| Tool | What it does |
|------|-------------|
| `start_proxy` | Auto-captures outbound traffic into a collection |
| `stop_proxy` | Stops traffic interception |
| `exec_with_proxy` | Starts the proxy and runs a dev command with it injected |
| `install_middleware` | Returns the inbound-capture snippet for your framework |
**🎭 Mock Server**
| Tool | What it does |
|------|-------------|
| `start_mock` | Starts the mock server for a collection on a given port |
| `stop_mock` | Stops the mock server |
| `get_mock_status` | Returns mock server status and active routes |
</details>
## 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.
```mermaid
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**
```yaml
# .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:
```bash
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:
```bash
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:
```bash
npm install reqly-middleware
```
```ts
// 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:
```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:
| Property | Values | Notes |
|----------|--------|-------|
| `field` | `status` \| `body` \| `latency` | **Required.** Use `field`, not `type`. |
| `operator` | `eq` \| `neq` \| `contains` \| `lt` \| `gt` | **Required.** |
| `value` | string, number, or boolean | **Required.** Expected value. |
| `path` | dot-notation string | Required when `field` is `body`. Path into the JSON body, e.g. `user.id` or `data.items.0.name`. |
**Common mistake:** writing `type: "status"` instead of `field: "status"` - this silently produces an assertion that never matches, always failing with "got undefined".
Examples:
```yaml
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.
```bash
reqly run users
```
Supports reporter formats and environments:
```bash
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
```bash
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
```bash
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:
```bash
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
<details>
<summary><strong>Do I need an AI agent to use Reqly?</strong></summary>
<br>
No. The localhost UI at <code>localhost:4242</code> works standalone - create collections, fire requests, inspect responses, all without an agent. The MCP interface is additive: when your agent is connected, it gets the same capabilities via tools. You can use both at the same time.
</details>
<details>
<summary><strong>How is this different from Postman or Insomnia?</strong></summary>
<br>
Three things:
1. <strong>Collections are YAML files in your repo</strong>, 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. <strong>Reqly is an MCP server</strong>. 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. <strong>No cloud dependency, ever.</strong> No account required, no sync, no telemetry. Everything runs on your machine.
</details>
<details>
<summary><strong>How is this different from Bruno?</strong></summary>
<br>
Bruno is the closest comparison - it's also local, file-based, and git-native. The key difference is the agent interface. Bruno has no MCP server; your agent can't call Bruno tools to fire requests or build collections programmatically. Reqly was designed from day one so that an AI agent is the primary user, with the UI as a secondary window into the same engine.
</details>
<details>
<summary><strong>Does Reqly send any data to the cloud?</strong></summary>
<br>
No. Reqly is a local process. Collections stay in <code>.reqly/</code> in your repo. Your API keys stay in <code>~/.reqly/config.json</code> on your machine. The prompt bar in the UI sends requests to your own API key directly from your browser - nothing routes through Reqly's servers, because there are no Reqly servers.
</details>
<details>
<summary><strong>Can I use Reqly without Cursor or Claude Code?</strong></summary>
<br>
Yes. Any MCP-compatible client works: Cursor, Claude Code, Claude Desktop, Gemini CLI, Codex, or anything that supports the MCP stdio transport. If your agent doesn't support MCP yet, you can still use the CLI (<code>reqly run</code>, <code>reqly run-flow</code>) and the localhost UI without any agent at all.
</details>
<details>
<summary><strong>My agent is looking for collections in the wrong directory. What do I do?</strong></summary>
<br>
This happens when your AI tool launches the Reqly process from a different working directory than your project. Fix it one of three ways:
1. <strong>Cursor / most editors</strong> - run <code>reqly setup cursor</code> again from inside your project directory. The setup command writes <code>${workspaceFolder}</code> into the MCP config so Cursor passes the right path at launch.
2. <strong>Claude Desktop</strong> - run <code>reqly use /path/to/your/project</code> to set the active project globally, then restart Claude Desktop.
3. <strong>Manual override</strong> - set the <code>REQLY_PROJECT_DIR</code> environment variable on the MCP server entry in your AI tool's config.
</details>
<details>
<summary><strong>Can I use Reqly in CI without an AI agent?</strong></summary>
<br>
Yes - that's the point of <code>reqly run</code> and <code>reqly run-flow</code>. Your agent builds and maintains the collection locally; CI just executes it. Use <code>--reporter junit</code> to get JUnit XML output that GitHub Actions, GitLab CI, and Jenkins parse natively into test dashboards.
```bash
reqly run my-collection --reporter junit > results.xml
```
Or generate the full GitHub Actions workflow automatically:
```bash
reqly export-flow "my-flow" --format github-actions
```
</details>
<details>
<summary><strong>Does the middleware capture requests in production?</strong></summary>
<br>
No - by design. <code>reqly-middleware</code> phones home to <code>localhost:4242</code> and is a silent no-op if Reqly isn't running. It will never capture traffic in a production environment where Reqly isn't present, and it never buffers or delays your requests (fire-and-forget, errors swallowed).
</details>
<details>
<summary><strong>What auth types does Reqly support?</strong></summary>
<br>
Bearer token, API Key (header or query param), Basic auth, and OAuth 2.0 with PKCE. Auth can be set at the collection level (applies to all requests) or overridden per-request. Your agent can configure auth via the <code>set_collection_auth</code> MCP tool - no manual YAML editing required.
</details>
<details>
<summary><strong>Can I import my existing Postman or Bruno collections?</strong></summary>
<br>
Yes. Reqly imports Postman v2.1 collections and Bruno collections out of the box:
```bash
reqly import postman-collection.json
reqly import bruno-collection/
```
Or via the MCP tool: your agent can call <code>import_collection</code> and pass the file path. Reqly also exports to Postman v2.1 and OpenAPI 3.0 if you need to go the other way.
</details>
<details>
<summary><strong>How do environment variables work?</strong></summary>
<br>
Reqly has three variable layers, resolved in this order:
1. <strong>.env files</strong> - auto-loaded from your project root (or configured via <code>set_dotenv_files</code>)
2. <strong>Environment variables</strong> - named sets like <code>dev</code>, <code>staging</code>, <code>prod</code>, stored in <code>.reqly/environments.yaml</code>
3. <strong>Collection variables</strong> - scoped to a single collection, useful for values like <code>baseUrl</code>
Use <code>{{varName}}</code> anywhere in a URL, header, or body. Switch environments with <code>reqly run --env prod</code> or via the UI dropdown.
</details>
<details>
<summary><strong>Does Reqly support GraphQL?</strong></summary>
<br>
Yes. The UI has a dedicated GraphQL workspace with schema introspection, syntax highlighting, and a variables panel. GraphQL requests are stored in collections the same as REST - your agent can create and run them via the same MCP tools.
</details>
<details>
<summary><strong>Can I run Reqly on a team? How do we share collections?</strong></summary>
<br>
Collections are plain YAML files in <code>.reqly/</code> inside your project repo. Sharing is just git - commit the folder and everyone on the team has the same collections. There's no account, no workspace invite, no cloud sync required. Secrets and API keys are stored in <code>~/.reqly/config.json</code> locally on each developer's machine and are never committed.
</details>
<details>
<summary><strong>What Node.js version does Reqly require?</strong></summary>
<br>
Node.js 18 or later. Reqly uses native <code>fetch</code>, ES modules, and the MCP SDK which all require Node 18+. Check your version with <code>node --version</code>.
</details>
<details>
<summary><strong>Port 4242 is already in use. Can I change it?</strong></summary>
<br>
Yes. Pass <code>--port</code> when starting:
```bash
reqly start --port 4243
```
Or set it in your MCP config args. The UI will open on whichever port you choose.
</details>
<details>
<summary><strong>How do pre/post scripts work?</strong></summary>
<br>
Each request can have a <code>preScript</code> and a <code>postScript</code> - small sandboxed JavaScript snippets that run before and after the request fires. They have access to a <code>reqly</code> object with methods to read and write environment variables:
```js
// 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)
```
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.
</details>
<details>
<summary><strong>How do I stop Reqly?</strong></summary>
<br>
```bash
reqly stop # stops the running instance
reqly status # check if an instance is running and which project it's on
```
Or press Ctrl+C in the terminal where Reqly is running. Reqly writes a lock file at <code>~/.reqly/running.json</code> to track the running instance - <code>reqly stop</code> reads this to find and signal the process.
</details>
<details>
<summary><strong>Can I switch projects without restarting?</strong></summary>
<br>
Yes. If a Reqly instance is already running, starting a new one in a different project directory hot-swaps the active project without restarting the server:
```bash
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.
</details>
<details>
<summary><strong>Is there a way to test webhooks?</strong></summary>
<br>
Yes - use the tunnel command to expose your local server to the internet and capture incoming webhook payloads:
```bash
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 <code>Captured</code> collection automatically.
</details>
## Star History
[](https://star-history.com/#RutvikPansare/Reqly)
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available