Reqly

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

• AWS SigV4 Auth

• Exporting Collections

• Mock Server

• Capture Inbound Requests

• Collections and Assertions

• Proof

• Why Reqly

• Recently Shipped

• Contributing

• FAQ

• Star History

• Releases

Related MCP server: EvalView

Proof (30 seconds)

Time savings on real developer workflows:

Reqly shifts API testing from a tedious manual chore to a rapid, agent-driven workflow. Your agent writes the YAML, constructs the flows, and exports the CI configuration—all without you leaving your editor.

Why Reqly beats Postman, Insomnia, and Bruno for AI-native developers (45 seconds)

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.

Git is your Enterprise RBAC. Stop paying per-user enterprise licenses just to set permissions on an API collection. Because Reqly collections are files in your repo, you automatically inherit the security policies of your Git provider. Use branch protections and CODEOWNERS to restrict who can edit production flows.

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.

No cloud dependency. There is no Reqly cloud. Collections stay in your repo. Secrets stay in ~/.reqly/config.json on your machine. Nothing is sent to Reqly's servers - because there are no Reqly servers. No account required, no telemetry, no sync.

Democratizes testing for PMs & QA. Postman's UI is intimidating for non-developers. With Reqly, non-technical team members can just ask their AI: "Run the checkout flow and tell me if tax is calculated correctly." The AI handles the auth, formatting, and JSON payloads, then explains the response in plain English. No developer hand-holding required.

What an agent session looks like (15 seconds)

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 (45 seconds)

Reqly runs on macOS, Linux, and Windows. Three ways in:

# 1. On any platform via npm (CLI + MCP server + web UI)
npm install -g getreqly

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

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

Or download the DMG directly from GitHub Releases - no npm, no Homebrew, no terminal required. The desktop app bundles its own copy of the Reqly server, so it is fully self-contained.

VS Code extension: install reqly.reqly from the VS Code Marketplace (works in Cursor, Windsurf, and every VS Code-compatible editor). It gives you a collection tree in the activity bar, a status bar environment switcher, Reqly: command palette commands, a "▶ Run with Reqly" CodeLens above fetch/axios/got calls in JS/TS, and schema validation with autocomplete for all .reqly/ YAML files. It talks to the same local server, so install Reqly itself first (any of the three ways above).

Connecting your AI agent:

• Desktop app users: on first launch a setup wizard appears ("Connect your AI Agent") with one-click buttons for Claude Desktop, Cursor, Windsurf, and VS Code. Each button writes that agent's MCP config for you - no JSON editing. Reachable again any time from the tray menu ("AI Agent Connections..."). If you have the CLI installed (Homebrew or npm), the wizard points agents at your CLI so brew upgrade keeps them current; otherwise it points them at the bundled server.

• CLI users: run

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".

Project directory resolution

Reqly determines which project directory to operate on based on a 4-level priority chain:

1. Flag: --project-dir (highest priority)

2. Environment Variable: `REQLY_PROJECT_DIR`

3. Saved Config: The path set by running `reqly use `

4. Current Directory: `process.cwd()`

Setup Methods by Host:

• VS Code-based editors (Cursor, Windsurf): These editors support dynamic macro interpolation. `reqly setup` configures them to pass `--project-dir ${workspaceFolder}` so Reqly dynamically follows whichever project is currently open in the editor window.

• Standalone hosts (Claude Desktop, Gemini CLI, Antigravity): These tools spawn one global MCP server process that is shared across all projects and do not interpolate macros. `reqly setup` omits the flag entirely. For these tools, you must run `reqly use ` inside your project directory to tell the global Reqly process which project to look at.

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. (Note: reqly init automatically creates .reqly/ and adds its runtime state files to your .gitignore.)

The fastest way to start with your own API (60 seconds)

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 (45 seconds)

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

📂 Workspace and Projects

🗂️ Collections and Requests

🌍 Environments and Variables

🔐 Auth

📋 OpenAPI Contract Validation

🔗 Flows

🕵️ Capture and Proxy

🌐 GraphQL

⚡ gRPC

run_request and create_request both support type: grpc natively. Place proto files in .reqly/protos/. Auth profiles auto-inject into gRPC Metadata.

Recently shipped (30 seconds)

• Markdown Docs Export - generate beautiful markdown API references directly from your collections

• Flows - multi-step automation tests (run, extract, assert, poll, conditional) with data-driven support. Chains REST, GraphQL, and gRPC steps in the same flow.

• 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

• AWS Signature V4 auth - compute and inject Authorization + X-Amz-Date for REST/GraphQL; presign WebSocket URLs for AppSync, IoT Core, and API Gateway WebSocket APIs. Supports temporary STS credentials (sessionToken).

• gRPC support - full BloomRPC-beating gRPC: unary RPCs, server/client/bidirectional streaming, proto-file loading with cross-file import support, server reflection (no .proto needed), auth profiles auto-inject into Metadata, JSON message scaffold auto-generated by create_request

• GraphQL workspace - dedicated editor with Headers tab, full schema introspection (with cache), Docs Explorer sidebar, a Saved Requests browser, operationName multi-op dropdown, queryFile support for external .graphql files, Prettify, Copy as cURL, GraphQL-aware response viewer (data/errors/extensions sections), and real-time subscription streaming via graphql-ws

• 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 (60 seconds)

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.

AWS Signature Version 4 (SigV4) Authentication

Reqly has built-in support for signing requests to any AWS API: API Gateway, AppSync, Bedrock, S3, IoT Core, and more. Use auth type awsv4.

REST and GraphQL - Header signing

# Per-request auth in collection YAML
name: invoke-bedrock
method: POST
url: https://bedrock-runtime.us-east-1.amazonaws.com/model/anthropic.claude-v2/invoke
auth:
  type: awsv4
  credentials:
    accessKey: "{{env.AWS_ACCESS_KEY_ID}}"
    secretKey: "{{env.AWS_SECRET_ACCESS_KEY}}"
    region: us-east-1
    service: bedrock
    sessionToken: "{{env.AWS_SESSION_TOKEN}}"  # optional - for STS temporary creds
headers:
  Content-Type: application/json
body: '{"prompt": "Hello from Reqly"}'

Reqly computes and injects these headers before sending:

• Authorization: AWS4-HMAC-SHA256 Credential=AKID/date/region/service/aws4_request, SignedHeaders=..., Signature=...

• X-Amz-Date: 20260702T163930Z

• X-Amz-Security-Token: <token> (only when sessionToken is set)

Set at collection level so every request inherits it - useful for an entire AWS API collection:

"Set collection auth for my-bedrock-api to awsv4 with region us-east-1 and service bedrock"

Your agent calls set_collection_auth with type: "awsv4" and the credential fields. All requests in that collection are signed automatically.

WebSocket - URL presigning (AppSync, IoT Core)

Browser WebSocket APIs cannot send custom headers. Reqly presigns the connection URL instead - appending X-Amz-Algorithm, X-Amz-Date, X-Amz-Credential, and X-Amz-Signature as query parameters. The wss:// scheme is always preserved.

Via the run_realtime MCP tool:

{
  "type": "websocket",
  "url": "wss://abc123.appsync-realtime-api.us-east-1.amazonaws.com/graphql",
  "awsAuth": {
    "accessKey": "AKIAIOSFODNN7EXAMPLE",
    "secretKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "region": "us-east-1",
    "service": "appsync"
  },
  "captureTimeout": 5
}

Best practice: use environment variables

Store credentials as environment variables in Reqly - never hardcode them in collection YAML:

# In Reqly UI or via MCP set_environment
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtn...
AWS_REGION=us-east-1
AWS_SESSION_TOKEN=FQoGZXIv...   # if using temporary creds

Then reference with {{env.AWS_ACCESS_KEY_ID}} in your request auth block. The credentials stay in your environment config - never committed to the YAML collection files in git.

📤 Exporting Collections (30 seconds)

You are never locked into Reqly. Because your collections are plain YAML files, you always own your data. To make migration even easier, Reqly provides built-in, freeform export formats to move your collections into other tools, documentation sites, or API gateways instantly:

• 📮 Postman (postman): Exports a standard Postman v2.1 JSON file. Perfect for importing directly into Postman, Insomnia, or other HTTP clients.

• ⚙️ OpenAPI (openapi): Generates an OpenAPI 3.0 JSON specification. Ideal for Swagger UI, generating client SDKs, or configuring API gateways.

• 📖 Markdown Docs (docs): Generates a beautiful Markdown (.md) API reference ready to be committed to your repository, wiki, or static site generator.

Via CLI:

reqly export docs my-collection
reqly export docs my-collection --output docs/api/my-collection.md

Via AI Agents: It's as simple as asking your agent. They can automatically export your APIs by calling the export_collection MCP tool:

"Export my 'users' collection to a Postman file so I can share it with the frontend team."

Capture Inbound Requests (Middleware) (45 seconds)

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 (30 seconds)

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 (45 seconds)

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 (45 seconds)

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

Workspace Management

You can configure Reqly to load collections from multiple project directories at once. This is perfect for microservices or monorepos where you have multiple related APIs open.

reqly workspace add <absolute_path>    # Adds a project to your workspace
reqly workspace remove <absolute_path> # Removes it
reqly workspace list                   # Lists all configured projects and named workspaces

For microservices teams there is also a named workspace model: a workspace maps stable repo aliases (shared across teammates) to machine-local paths, stored at ~/.reqly/workspaces/<name>/workspace.yaml (never committed to any repo).

reqly workspace create checkout-team                       # scaffold the workspace
reqly workspace link checkout-team auth /repos/auth-svc    # alias "auth" -> local path
reqly workspace link checkout-team payments /repos/pay-svc
reqly workspace use checkout-team                          # set active workspace

Agents can do the same via the create_workspace, link_workspace_repo, use_workspace, and list_workspaces MCP tools, and the UI has a workspace dropdown above the project list. Aliases are the foundation for cross-repo flows (repo: auth on a flow step - coming next).

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

Contributing (60 seconds)

Reqly is an open-source execution engine built for AI agents. We welcome contributions across the stack!

How you can help

• Engine & Protocols: Add new auth types (Digest, NTLM) or enhance the JS script sandbox with more built-in helper libraries (e.g., mock data generation).

• MCP Toolkit: Write new tools in src/mcp/tools/ (e.g., importers for Swagger 2.0 or Insomnia) to give agents more capabilities.

• UI & Polish: Enhance the React frontend (src/ui/) with themes, better syntax highlighting, or UI fixes.

Core Architectural Principle: Tool-First

Every capability must be a tool first. If it can't be called via MCP, it doesn't exist as a feature. The UI is a visual wrapper around the same tools - it never has capabilities the MCP interface lacks. Keep AI logic outside the engine; Reqly is the dumb execution layer for smart agents.

Local Setup

git clone https://github.com/RutvikPansare/Reqly.git
cd Reqly
npm install
npm run dev

Testing Standards

We use Vitest (npm test). Engine logic (src/engine/) and MCP tool contracts (src/mcp/) require strict TDD with 100% coverage. UI interactions are tested flexibly. Before submitting a PR, ensure all tests pass.

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