# Kurlo > Kurlo is a free, open-source (MIT) desktop API client for HTTP, GraphQL, gRPC, WebSocket, Socket.IO, SSE and MCP. No account, no seats, no cloud, no telemetry: collections are plain YAML files on your disk, and Git is how a team shares them. It supports common Postman `pm.*` APIs, imports Postman v2 JSON and v3 Native Git folders, and reads Insomnia v4, Bruno, OpenAPI and HAR. It also has a local mock server, a collection runner, and browser CORS and CSP checks. For AI agents, `kurlo mcp` is an MCP server that lists, runs and edits the saved requests of a workspace and reads what the user sent from the app. `npx -y @kurlo/cli mcp install` adds it to Claude Code, Cursor, Codex, VS Code and other clients. `kurlo run` runs collections in CI. # Installation Source: https://kurlo.dev/docs/getting-started/installation/ > Install Kurlo on macOS, Windows or Linux, and get past the first-run prompts. Kurlo publishes a build for each platform on the [releases page](https://github.com/stormhop/kurlo/releases/latest). Choose your platform for installation steps and first-launch prompts. # macOS Source: https://kurlo.dev/docs/getting-started/installation/macos/ > Download the DMG and handle the first-launch prompt. **Requirements:** macOS 15 Sequoia or later. Kurlo draws its window with the system WebKit and is tested on the version macOS 15 ships with; it may start on older macOS, but that is not tested. Apple Silicon and Intel are both supported. 1. Download `kurlo--darwin-universal.dmg`. 2. Open the disk image and drag **Kurlo.app** to `/Applications`. 3. Launch Kurlo from Spotlight or the Applications folder. Current builds are not Apple-notarized, so macOS blocks the first launch. Click **Done**, then open *System Settings → Privacy & Security* and click **Open Anyway** next to Kurlo. Or run `xattr -dr com.apple.quarantine /Applications/Kurlo.app` once. See the [troubleshooting guide](https://kurlo.dev/docs/troubleshooting/installation/#macos-kurlo-not-opened-or-apple-could-not-verify-kurlo). # Windows Source: https://kurlo.dev/docs/getting-started/installation/windows/ > Choose an installer, MSIX package, or portable build. **Requirements:** Windows 10 1903+ or Windows 11, on x64 or Arm64. Pick the files ending in `amd64` for an Intel or AMD processor and `arm64` for a Snapdragon or other Arm processor; *Settings → System → About → System type* says which one you have. Installer (recommended) `kurlo--windows-amd64-installer.exe` installs for you alone into `%LOCALAPPDATA%\Programs\Kurlo`. No administrator rights, and the in-app updater can replace the app later. MSIX package `kurlo--windows-amd64.msix` installs through App Installer, which lists one permission — Uses all system resources — that every packaged desktop app needs. Portable app `kurlo--windows-amd64-portable.exe` runs from any folder without installing, for a machine where you cannot or do not want to install software. It updates itself in place. The portable app adds no Start menu entry and keeps your workspaces and settings in your user profile, in the same place as an installed Kurlo, so the two share data. It needs the Microsoft Edge WebView2 Runtime, which Windows 11 and up-to-date Windows 10 already include; the installer adds it when it is missing. Releases up to 3.0.4 publish the same program as `kurlo-windows-amd64.exe`. If an older copy installed for all users in Program Files is found, the installer offers to remove it; Windows asks for permission once for that, and your data is kept. SmartScreen may warn because the installer is not Authenticode-signed yet. The MSIX package is signed only when the release job had the publisher certificate; an unsigned package needs extra trust setup before Windows installs it. # Linux Source: https://kurlo.dev/docs/getting-started/installation/linux/ > Install system dependencies and launch the AppImage. **Requirements:** x64 with Ubuntu 22.04 or later, Debian 12 or later, or Fedora 37 or later, plus GTK 3, WebKitGTK 4.1 and FUSE 2 from your distribution's package manager. 1. Install the libraries Kurlo draws its window with: ```sh sudo apt install libgtk-3-0 libwebkit2gtk-4.1-0 libfuse2 # Ubuntu, Debian sudo dnf install gtk3 webkit2gtk4.1 fuse-libs # Fedora ``` 2. Download `kurlo--linux-amd64.AppImage`. 3. Make it executable and run it: ```sh chmod +x kurlo-*.AppImage ./kurlo-*.AppImage ``` # Verify the download Source: https://kurlo.dev/docs/getting-started/installation/verify/ SHA-256 checksums are published in `SHA256SUMS.txt`; auto-updates use the values embedded in `latest.json`. Verify before running: ```sh shasum -a 256 kurlo-*.dmg # Compare against the value on the releases page. ``` # Auto-updates Source: https://kurlo.dev/docs/getting-started/installation/updates/ Kurlo checks `latest.json` from `stormhop/kurlo` after launch. Open **Settings → About** to check and install by hand. **Settings → About → Install updates automatically** controls whether a discovered update installs in the background. Updates are verified against both the SHA-256 value and the minisign signature from the manifest before they install. An AppImage updates in place: Kurlo replaces the `.AppImage` file you started it from, so keep that file in a folder you can write to, such as `~/Applications`. AppImages from Kurlo 2.2.3 and earlier cannot install updates. Download 2.2.4 or later by hand once, and updates install from then on. # Your first request Source: https://kurlo.dev/docs/getting-started/first-request/ > Send and save a request, set a base URL through an environment, and check the response with a test. This walkthrough takes about five minutes. By the end you'll have: 1. A workspace with one collection. 2. A saved `GET` request against a public API. 3. An environment with a base URL variable. 4. A test script asserting the response. On a new profile, the **Welcome to Kurlo** screen offers **New request**, **Import a collection**, and **Open a workspace**. **Try an example** opens a `GET https://httpbin.org/get` draft. Click **Send** when you're ready. Choose **Skip for now** to dismiss the screen, or reopen it later with `Cmd/Ctrl K` → **Welcome screen**. ## 1. Create a workspace Workspaces are top-level containers — think one per project or per client. On first launch Kurlo creates a **Default** workspace; you can rename it or add more from the workspace switcher in the top-left. ## 2. Send an ad-hoc request - Press `Cmd/Ctrl N` or click `+` in the tab bar — a new HTTP request opens right away. Other protocols live in the picker at the start of the address bar. - Paste `https://httpbin.org/get?lang=go&runtime=wails` into the URL bar. - Hit `Cmd/Ctrl Enter` (or click **Send**). The response panel shows the JSON body with syntax highlighting, response headers, timing, and size. The URL bar is always one line high. A URL longer than the bar scrolls sideways as you type or move the cursor with the arrow keys, `Home` and `End`. Swipe sideways on the trackpad or turn the mouse wheel over the URL to see the rest of it without moving the cursor. The bar shows the start of the URL again when you click elsewhere. > Tip: you can paste a `curl ...` command into the URL field — Kurlo will parse method, headers, params, and body automatically. ### Bulk edit **Params**, **Headers**, and the form body types each have a **Bulk edit** toggle that swaps the table for its text form — one `key:value` per line, with `//` in front of a line to disable it: ``` Content-Type:application/json Authorization:Bearer {{token}} //X-Debug:1 ``` It is the quickest way to paste a block of headers from somewhere else, or to add and reorder a dozen rows at once. Switching back rebuilds the table. Descriptions and attached files stay with their key, so a round trip through bulk edit does not lose them. ## 3. Save it to a collection - In the Collections sidebar, click **New collection** (`+`) and name it `Examples`. - Return to the request tab and name the request `Get with query`. - Click **Save** (or press `Cmd/Ctrl S`). In **Save request**, open the collection list, select `Examples`, and click **Save**. The request now lives in the sidebar tree. Drag it to reorder it or [move it to another folder in the same collection](https://kurlo.dev/docs/guides/workspaces/requests/#reordering-requests). ## 4. Parameterize with an environment Hard-coded URLs don't survive across staging and prod. Replace the host with a variable: - Open **Environments** in the activity rail and click **New environment** (`+`) to create `Local`. - Add `baseUrl = https://httpbin.org`. In manual-save mode, click **Save** in the environment editor. - Select `Local` from the environment switcher if it is not already active. - Edit the request URL to `{{baseUrl}}/get?lang=go&runtime=wails`. - Send again — same result, but now portable. See the [environments guide](https://kurlo.dev/docs/guides/environments/) for active environments, collection variables, and script-created values. Use the **Headers** tab for API-specific metadata such as trace IDs, content negotiation, or custom client headers: `Host` works here: set it to reach a virtual host or a service behind a load balancer, and the connection still goes to the URL's address. A handful of others — `Content-Length`, `Transfer-Encoding`, `Connection`, `Upgrade`, `Keep-Alive`, `TE`, `Trailer`, and the `Proxy-*` pair — control how the request is framed on the connection, so Kurlo sets them itself and does not send yours. When you have one enabled, the response panel says which ones were left off rather than letting you wonder why the server ignored them. ## 5. Assert with a test script Open the **Scripts** tab on the request and paste: ```js pm.test("status is 200", () => pm.response.to.have.status(200)) const body = pm.response.json() pm.test("query is echoed back", () => { pm.expect(body.args.lang).to.equal("go") }) ``` Send the request again. Your tests show green in the response **Scripts** panel. ## Next steps - [Configure auth](https://kurlo.dev/docs/guides/authentication/) — Bearer, OAuth2, AWS SigV4, etc. - [Import an existing collection](https://kurlo.dev/docs/guides/import-export/). - [Full scripting API](https://kurlo.dev/docs/reference/scripting-api/). # Migrating to Kurlo Source: https://kurlo.dev/docs/getting-started/migrating/ > Import collections from Postman, Insomnia, or Bruno and verify they work in Kurlo. Choose your source app for import steps and details on what carries over. Then verify your collection with a request you use often. # From Postman Source: https://kurlo.dev/docs/getting-started/migrating/postman/ > Move Postman collections, environments, and scripts to Kurlo. For a collection with native gRPC, WebSocket, Socket.IO, or MCP requests, use a [Postman v3 Native Git folder](https://kurlo.dev/docs/guides/import-export/postman/#postman-v3-folders). In Kurlo choose **Postman v3 collection folder**, or drop the folder into the window. These steps cover Postman's v2.0 and v2.1 collection JSON. ## Export from Postman 1. Open Postman. 2. Right-click the collection → **Export**. 3. Choose **Collection v2.1** → **Export**. 4. Save the `.json` file somewhere you'll remember. If you have environments too: Postman left sidebar → **Environments** → `⋯` next to each environment → **Export**. Save those `.json` files alongside the collection. ## Import into Kurlo In Kurlo's sidebar header, click **Import collection** next to **+**. Select **Postman collection**, click **Import**, then pick the exported `.json`. Kurlo creates a collection with the same name and restores its folder tree. You can also drop the file into the Kurlo window. Use the **Postman collection** picker for exported Postman environments or globals as well. Kurlo recognises them from the JSON. ## What carries over | Postman concept | Maps to in Kurlo | |-----------------|------------------| | Collection name + folder tree | Collection with nested folders, including empty folders | | Request name, method, URL, params, headers, body (raw / form-data / urlencoded / binary / GraphQL) | Imported as request fields. File bodies keep their file paths. | | Authentication: Basic, Bearer, API Key, Digest, OAuth 2.0 | Request auth stays on the request. Collection and folder auth become [defaults](https://kurlo.dev/docs/guides/collection-defaults/). | | AWS Signature v4 | Preserved with region / service / access keys | | OAuth 1.0 | Preserved: keys, secrets, signature method, realm, callback, verifier and the header/query choice | | Pre-request and test scripts | Imported into Kurlo's sandboxed script fields — see compatibility notes below | | Environments (variables) | One Kurlo environment per Postman environment | | `{{variable}}` syntax everywhere | Preserved literally — Kurlo resolves them the same way | ## Pre-request / test script compatibility Postman scripts are JavaScript with Postman's `pm.*` API. Kurlo supports sandboxed JavaScript for new imports and keeps legacy [Tengo](https://github.com/d5/tengo) script fields for older requests. The shared `pm.*` API mirrors the common Postman surface for headers, variables, environments, response JSON, tests, and logs. Most simple Postman scripts import with minimal edits: | Postman | Kurlo equivalent | |---------|------------------| | `pm.request.headers.add({key, value})` | `pm.request.headers.set("key", "value")` | | `pm.response.json()` | `pm.response.json()` ✓ same | | `pm.test("name", function () { ... })` | `pm.test("name", () => { ... })` or `pm.test("name", expr)`; see [Scripting API](https://kurlo.dev/docs/reference/scripting-api/) | | `pm.environment.set("k", "v")` | `pm.environment.set("k", "v")` ✓ same | | `pm.collectionVariables.set(...)` / `pm.globals.set(...)` | ✓ same; see [Variable scopes](https://kurlo.dev/docs/reference/scripting-api/variables/) | | `pm.info.requestName`, `pm.info.iteration` | ✓ same | | `pm.cookies.get(...)` / `.has(...)` | ✓ same (read-only) | | `pm.execution.skipRequest()` | ✓ same | | `CryptoJS.HmacSHA256(...)` | ✓ works via the [CryptoJS shim](https://kurlo.dev/docs/reference/scripting-api/crypto/#cryptojs), or use `pm.crypto.hmacSha256(...)` | | `pm.sendRequest(...)` | ✓ same, once **Allow pm.sendRequest** is enabled in the request's Settings tab | | `tests["name"] = ...`, `responseBody`, `postman.setEnvironmentVariable(...)` (legacy) | ✓ same; see [Postman legacy globals](https://kurlo.dev/docs/reference/scripting-api/compatibility/#postman-legacy-globals) | | `pm.variables.replaceIn("{{baseUrl}}/x")`, `xml2Json(...)` | ✓ same | | `postman.setNextRequest(...)` | Not supported — Kurlo's Collection Runner runs in declared order | | `require("lodash")`, `ajv`, `tv4`, `uuid`, `crypto-js`, `chai` | ✓ works via Kurlo's [bundled stand-ins](https://kurlo.dev/docs/reference/scripting-api/compatibility/#require) | | `require("...")` of any other Node.js library (`xml2js`, `moment`, `cheerio`, …) | Not supported — the sandbox has no filesystem, process access or real npm modules. Hashing and HMAC are covered by `pm.crypto` / `CryptoJS`, XML by `xml2Json`, HTTP calls by `pm.sendRequest`. | | `setTimeout` / `async` / `await` | Not supported — the sandbox has no event loop. `pm.sendRequest` is synchronous, and its callback runs immediately. | After import, open the *Scripts* tab on a request and run a smoke request. If a script fails, the response panel shows a script-error block with the line number. ## What doesn't import - **Postman monitors** — a server-side feature with no direct equivalent; the [CLI runner](https://kurlo.dev/docs/guides/cli-runner/) on a schedule covers the same ground. Postman **mocks** do have an equivalent, and it runs locally: imported saved responses become [examples](https://kurlo.dev/docs/guides/examples/), which the [mock server](https://kurlo.dev/docs/guides/mock-server/) serves over HTTP without an account. - **Postman Flows / workflows** — same. - **Personal teams / sharing** — Kurlo is local-only. To send a collection back to Postman, open its **⋯** menu and choose **Export…**. Choose **Postman collection v2.1** for a single JSON file or **Postman collection v3 (YAML folder)** to open native gRPC requests with [Postman Local Files](https://kurlo.dev/docs/guides/import-export/postman/#export-to-postman-v3). See [protocol support by format](https://kurlo.dev/docs/guides/request-types/portability/) for details. # From Insomnia Source: https://kurlo.dev/docs/getting-started/migrating/insomnia/ > Export resources from Insomnia and import them into Kurlo. Insomnia uses its own export format which is broadly similar to Postman's. Kurlo can import it directly. ## Export from Insomnia Export the collection from Insomnia as **Insomnia v4 (JSON)**. ## Import into Kurlo Click **Import collection** in Kurlo's sidebar. Select **Insomnia export**, click **Import**, then select the JSON file. You can also drop the file into the Kurlo window. ## What carries over Kurlo creates one collection from the file and reconstructs folder paths from the parents of imported requests. The importer handles HTTP, GraphQL, gRPC, WebSocket, and Socket.IO requests. Insomnia folder environment values become entries in the request's [Vars tab](https://kurlo.dev/docs/guides/environments/request-variables/). Inner folders override outer folders, and variables already on the request take priority. ## Insomnia-specific gotchas - Create [Kurlo environments](https://kurlo.dev/docs/guides/environments/manage/) for any named Insomnia environments you want to use. Insomnia environment resources do not create Kurlo environments. - Replace Insomnia-specific template tags with Kurlo variables or pre-request scripts. # From Bruno Source: https://kurlo.dev/docs/getting-started/migrating/bruno/ > Import an OpenCollection YAML or legacy .bru collection folder into Kurlo. Use your existing Bruno collection folder. Kurlo reads OpenCollection folders with `opencollection.yml` and legacy Bruno folders with `bruno.json` and `.bru` files. ## Import into Kurlo 1. Open the destination workspace in Kurlo. 2. In the sidebar, click **Import collection** next to **+**. Select **Bruno / OpenCollection**, then click **Import**. 3. Select the collection's root folder. You can also drop that folder into the Kurlo window. ## What carries over Kurlo recreates the collection with its requests and folder structure. It adds environments from the source collection's `environments/` folder to the current workspace. Supported headers, authentication, and scripts at collection and folder level become [defaults](https://kurlo.dev/docs/guides/collection-defaults/). See [Bruno import details](https://kurlo.dev/docs/guides/import-export/bruno/) for how collection, folder, and request variables are mapped. ## Verify the import Select an imported environment and check the variables and credentials used by a request you send often. Kurlo copies script source, so review any `bru.*` calls and replace them with equivalents from the [Kurlo scripting API](https://kurlo.dev/docs/reference/scripting-api/). Then [verify the imported request](https://kurlo.dev/docs/getting-started/migrating/verify/). # Verifying the import Source: https://kurlo.dev/docs/getting-started/migrating/verify/ > Check imported auth and variables, then send a request to verify its response. After importing, do a smoke test: 1. Open the most-used request from the collection. Check headers, body, and auth all look right. 2. Pick the active environment with the environment switcher in the title bar. Confirm the variables resolve: in the URL bar, a `{{variable}}` the environment does not define is marked in red, and one it does define stays plain. 3. Press *Send*. The response should match what you'd get in the source app. Kurlo leaves your source files untouched. If something doesn't carry over correctly, you can import the collection again or file an issue with an anonymized sample. ## Keeping both tools in sync You can keep Kurlo and Postman around in parallel during transition: - To move a collection back to Postman, open its **⋯** menu and choose **Export…**. See [Postman export formats](https://kurlo.dev/docs/guides/import-export/postman/#export-to-postman-v3) to choose between JSON and a YAML folder. - Use a [Git-backed workspace](https://kurlo.dev/docs/guides/git-workspaces/open/) to track changes to your collections. Kurlo stores shared data as YAML and keeps local secrets outside Git. Once you're committed to Kurlo, the export pipeline still works — your data is never trapped. # Request types Source: https://kurlo.dev/docs/guides/request-types/ > HTTP, GraphQL, SSE, WebSocket, Socket.IO, gRPC, MCP, and AI requests in Kurlo. Kurlo has separate request modes for protocols that behave differently on the wire. Each mode changes the editor tabs, send/connect controls, response panel, and export behavior to match. # Choose a request type Source: https://kurlo.dev/docs/guides/request-types/choose/ > Find the protocol picker and compare what each request type supports. A new request always starts as HTTP — the `+` in the tab bar, `Cmd/Ctrl N`, and **Add request** in the sidebar open it straight away, with no dialog. To use another protocol, pick it from the menu at the start of the address bar, or run **New GraphQL request**, **New WebSocket request**, **New Socket.IO request**, **New gRPC request**, **New MCP request**, or **New AI request** from the command palette. The picker holds both decisions: the HTTP methods on the left, the other protocols on the right. A draft can switch protocol at any time — pick `POST` on a GraphQL draft and it becomes an HTTP request. A saved request can switch until it has a URL; after that its protocol is fixed, the picker still changes an HTTP request's method, and a request of any other type shows its protocol without a menu. ## At a glance | Type | Use it for | Main tabs | Response surface | Desktop Collection Runner | |------|------------|-----------|------------------|----------------| | [HTTP](https://kurlo.dev/docs/guides/request-types/http/) | REST, JSON APIs, forms, files, regular request/response flows | Params, Auth, Headers, Vars, Body, Scripts, Settings | Body, Headers, Scripts | Yes | | [GraphQL](https://kurlo.dev/docs/guides/request-types/graphql/) | Queries, mutations, variables, schema exploration | Query, Auth, Headers, Vars, Schema, Scripts, Examples | Body, Headers, Scripts | Yes | | [SSE](https://kurlo.dev/docs/guides/request-types/sse/) | `text/event-stream` subscriptions over HTTP | Params, Auth, Headers, Body, Settings | SSE event stream | No | | [WebSocket](https://kurlo.dev/docs/guides/request-types/websocket/) | Raw `ws://` / `wss://` sessions | Params, Auth, Headers, Message, Settings | Frames, handshake, logs | No | | [Socket.IO](https://kurlo.dev/docs/guides/request-types/socket-io/) | Socket.IO servers with namespaces/events | Params, Auth, Headers, Events, Message, Settings | Events, handshake, logs | No | | [gRPC](https://kurlo.dev/docs/guides/request-types/grpc/) | Protobuf RPCs with metadata/reflection/proto files | Message, Auth, Metadata, Vars, Service definition, Scripts, Settings | Messages, metadata, trailers, scripts | Yes | | [MCP](https://kurlo.dev/docs/guides/request-types/mcp/) | Model Context Protocol servers — list their tools and call one by hand | Arguments, Auth, Headers, Scripts, Settings | Result, raw exchange, notifications | No | | [AI](https://kurlo.dev/docs/guides/request-types/ai/) | Prompts to OpenAI, Anthropic and OpenAI-compatible models, with MCP tools | Prompt, Auth, Headers, Tools, Scripts, Settings (model) | Conversation, raw stream, tests | No | The [CLI runner](https://kurlo.dev/docs/guides/cli-runner/run/#what-it-runs) handles HTTP and GraphQL. Use the desktop Collection Runner to include gRPC. # HTTP Source: https://kurlo.dev/docs/guides/request-types/http/ > Send REST requests with methods, parameters, headers, and bodies. HTTP is the default mode. It supports: - Methods: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`, and `SSE`. - Query params, path variables, and headers as editable rows. - Auth, body, scripts, request notes, and per-request settings. - JSON, text, XML, HTML, form-data, urlencoded, GraphQL-shaped body, and binary-file bodies. - cURL import from the URL bar. Use HTTP for normal REST APIs. Use the `SSE` method only when the endpoint keeps an event stream open. The method menu lists the HTTP methods on the left and the other protocols on the right. To copy the request as cURL or client code, open [Code snippets](https://kurlo.dev/docs/guides/code-generation/). ## Suggestions while you type Kurlo finishes what you are typing in faded text. Press `Tab` to accept it, or `Escape` to hide it. - **URL.** Start typing a URL and Kurlo offers the rest of one you have sent or saved in this workspace, newest history first. In the URL field, `→` at the end of the text accepts too. Typing the start of a request's name offers that request's URL instead, as in `create order → {{baseUrl}}/orders`. Suggestions come from requests of the same kind, so an HTTP request does not offer WebSocket addresses. - **JSON body.** When the request has [saved examples](https://kurlo.dev/docs/guides/examples/), Kurlo offers the next key at the point where one can go: inside quotes you have opened, or on a new line after a comma. It uses the example bodies of this request, including the ones an OpenAPI import created from the spec's schemas, follows the nested object you are in, and skips keys that are already there. ## Path variables A path segment that starts with a colon is a path variable: type `{{baseUrl}}/users/:userId/posts/:postId` and the **Params** tab lists `userId` and `postId` under **Path variables**, below the query params. Fill in the values there, and Kurlo puts them into the URL when it sends the request, so `/users/:userId` goes out as `/users/42`. The URL field keeps showing `:userId`. - The rows follow the URL. Adding `:name` to the path adds a row, and removing it from the path removes the row. Renaming a variable means editing the URL. - Only a whole segment counts. `/users/:id` has a variable, while `/v1:beta` and `http://localhost:8080` do not, and the query string and fragment are left alone. - A value can use `{{variables}}`, such as `{{userId}}` from the environment. - Characters that would change the URL's structure, such as `/`, `?`, `#` and spaces, are percent-encoded. Sequences that are already encoded, like `%2F`, are kept as they are. - A variable with an empty value stays in the URL as `:name`. - Pre-request scripts see the URL with `:name` in it, as Postman's do, and can read and change the values with [`pm.request.pathVariables`](https://kurlo.dev/docs/reference/scripting-api/). - Path variables apply to HTTP, GraphQL, and SSE requests. Copy as cURL and generated code put the values into the URL. The mock server treats `:name` as "any value" when it matches requests against saved examples. # GraphQL Source: https://kurlo.dev/docs/guides/request-types/graphql/ > Send queries and mutations, provide variables, and explore a schema. GraphQL requests use `POST` and store the query, variables, and operation name as a GraphQL payload. The Query tab is optimized for editing GraphQL text and variables; the Schema tab can hold an imported schema or an introspection result. GraphQL still uses the normal auth, headers, scripts, environments, cookies, and response viewer paths. Exports preserve GraphQL where the target format supports it. # Server-Sent Events (SSE) Source: https://kurlo.dev/docs/guides/request-types/sse/ > Subscribe to an event stream and see events as they arrive. ## Server-Sent Events SSE is an HTTP request with long-lived streaming semantics: 1. Create an HTTP request. 2. Set the method to `SSE`. 3. Enter the stream URL and any auth/headers. 4. Press **Connect**. Kurlo adds `Accept: text/event-stream`, `Cache-Control: no-cache`, and `Connection: keep-alive` when building the request. Events appear as they arrive and the session is written to history once the stream connects or errors. An SSE request has no Scripts tab: a subscription is opened rather than sent, and pre-request and test scripts do not run on that path. Reconnection is configurable — see [SSE-specific settings](https://kurlo.dev/docs/guides/request-settings/streaming/#sse-specific-settings). The `SSE` method subscribes with a `GET` and no body. An endpoint that streams events back from a `POST` — the streaming mode of most LLM APIs — is sent as an ordinary `POST`: Kurlo reads the stream until the server closes it and shows the raw events as the response body, within the request timeout. The SSE event list keeps the latest events bounded for UI performance. Clear or restore visible events from the SSE panel while the session is open. # WebSocket Source: https://kurlo.dev/docs/guides/request-types/websocket/ > Connect to a WebSocket endpoint and send or save frames. WebSocket requests connect to `ws://` or `wss://` URLs. Kurlo shows: - A handshake record with request/response headers. - Incoming/outgoing frames. - Text, binary, ping, pong, close, reconnect, and error events. - Reconnect settings and a max-message-size guard. Sending a close frame ends the session even when the server never answers it: Kurlo waits one second for the server's reply, then closes the connection. Use the Message tab to send a text or binary payload after connecting. Per-request headers and cookies are applied to the handshake, and so is the Authorization tab — Bearer, Basic, Digest and API-key auth all go out with the upgrade request, the same way they would on an ordinary send. There is no Scripts tab: the handshake does not run pre-request or test scripts. ## Saved messages **Saved** in the Message tab keeps messages you send again and again: a subscribe frame, a ping in your own format, a test payload. Type the message, open **Saved**, name it and press **Save current**. Click a saved message to put it back in the editor, or use its send button to send it straight away while connected. A request keeps up to 100 saved messages of up to 256 KB each; at the limit **Save current** is turned off until you delete one. From nine messages on, a search field above the list finds messages by name, content, event or argument. A request file that already holds more than 100 shows the first 100 and finds the rest by search; nothing is removed. Saved messages are stored with the request as `savedMessages` in its YAML file, so they are shared through Git with the rest of the collection. Socket.IO requests have the same menu next to the event name; a saved Socket.IO message keeps the event name, every argument and the **Ack** setting. # Socket.IO Source: https://kurlo.dev/docs/guides/request-types/socket-io/ > Work with namespaces, events, arguments, and acknowledgements. Socket.IO mode speaks the Socket.IO protocol rather than raw WebSocket frames. Configure: - Client version: v2 or v3. - Path, usually `/socket.io`. - Namespace, usually `/`. - Event name, arguments, and ack behavior. Empty arguments are not sent; to send an empty string, write `""` in JSON. - Reconnect attempts and interval. Socket.IO events are displayed with namespace, direction, args, and system/error rows. Cookies, headers, and the Authorization tab are applied to the Engine.IO handshake unless the request disables the cookie jar. As with WebSocket, there is no Scripts tab. # gRPC Source: https://kurlo.dev/docs/guides/request-types/grpc/ > Discover or import services, send protobuf messages, and read responses. gRPC requests target `host:port` or a `grpc://` / `grpcs://` style target. Kurlo can discover services by reflection when enabled, or use a selected `.proto` file with import paths. The request body is JSON in protobuf JSON shape. Metadata lives in its own tab. The response panel separates: - Messages. - Response metadata. - Trailers. - Script output and test results. gRPC supports pre-request/test scripts, environment variables, collection defaults, and runner reports. A long server stream keeps its latest 500 messages in the Messages list and the response body. Messages keep their numbers, so the list then starts at the first one still kept; the response size still counts every message received. For servers that require mutual TLS, set a **Client certificate (mTLS)** in the gRPC **Settings** tab. It works the same way as for HTTP — see [Client certificate](https://kurlo.dev/docs/guides/request-settings/client-certificates/#client-certificate-mutual-tls) — and is sent whenever the call uses TLS (**Use TLS** on, or a `grpcs://` target). Reflection uses the same connection, so it works against mTLS servers too. To bring a native gRPC request from Postman, import its [Postman v3 folder or `*.request.yaml` file](https://kurlo.dev/docs/guides/import-export/postman/#postman-v3-folders). To take a native gRPC request into Postman, [export its collection as a Postman v3 folder](https://kurlo.dev/docs/guides/import-export/postman/#export-to-postman-v3). Add the service's `.proto` files in Postman if the server does not support reflection. # MCP requests Source: https://kurlo.dev/docs/guides/request-types/mcp/ > Discover a server and call its tools or read resources and prompts. ## MCP An MCP request calls a [Model Context Protocol](https://modelcontextprotocol.io) server — the servers agents talk to — without an agent in the loop. Kurlo speaks protocol revision **2026-07-28**, which is stateless: every call is a single HTTP POST to the server's endpoint, so an MCP call is an ordinary saved request that can be replayed, diffed, scripted and committed. Most servers in use today were built for the earlier revisions **2025-11-25**, **2025-06-18** and **2025-03-26**, which need a session. Kurlo finds that out by itself: when a server does not answer the stateless call, Kurlo sends `initialize` and `notifications/initialized`, keeps the `Mcp-Session-Id` the server hands out, and sends that call and the later ones to the same endpoint in the session. The panel then shows the revision next to the server's name, for example *MCP 2025-06-18*. If the server forgets the session, Kurlo opens a new one and sends the call again. The handshake carries the request's URL, headers and auth, but not its scripts, which run once around the call itself. To pin a revision, set `mcpProtocolVersion` on the request in its YAML file. Put the server's endpoint in the URL bar, then press **Discover**. Kurlo calls `server/discover` and follows it with `tools/list`, `resources/list` and `prompts/list` for the capabilities the server actually declares, so a server with no prompts is never asked for any. The panel then names the server, its version and what it holds. Choose a method and, for `tools/call`, `resources/read` or `prompts/get`, the tool, resource or prompt to address. Picking a tool seeds the **Arguments** editor from the tool's own input schema, and the arguments are checked for being a JSON object before anything is sent. The response panel has three views: - **Result** — the content blocks the server returned, its `structuredContent`, and, when a tool asked for more input, the `inputRequests` it sent back. - **Raw exchange** — the JSON-RPC envelope exactly as it arrived, including the individual frames when the server answered with a stream. This is the view that makes a failing tool call diagnosable. - **Notifications** — the progress and log notifications a streamed answer carried before its result. What Kurlo checks on your behalf: - **A tool that contradicts its own output schema is called out.** If the server publishes an `outputSchema` and its `structuredContent` does not match, the mismatch is listed as a warning — and the content is still shown, because the server is the one at fault. - **A tool whose `x-mcp-header` annotations the specification forbids cannot be called.** Kurlo names the reason instead of quietly dropping the tool from the list, which is what a conforming agent client does. - **Headers the protocol derives from the body are yours to read, not to set.** `Mcp-Method`, `Mcp-Name`, `MCP-Protocol-Version` and the `Mcp-Param-*` headers are built from the call; a header of the same name in the Headers tab is replaced and you are told so, because a server must reject a request whose headers and body disagree. Auth, proxy, client certificates, redirects and the response cap are the ordinary HTTP ones — an MCP call is an HTTP request, and it carries the same settings. Not in this release: the **stdio** transport, so servers launched as a local command (`npx some-server`) cannot be reached yet; the old HTTP+SSE transport of revision `2024-11-05`; `subscriptions/listen`; and sampling, which Kurlo declines because it has no model and is not going to acquire one. # AI requests Source: https://kurlo.dev/docs/guides/request-types/ai/ > Choose a provider and model, send prompts, and use MCP tools. ## AI An AI request sends a prompt to a language model and shows the answer as a conversation. Pick the provider and the model in the box next to the URL: **OpenAI**, **Anthropic**, **OpenRouter**, **Groq**, **Ollama**, **LM Studio**, or **Custom URL** for anything else that speaks the OpenAI Chat Completions API, such as vLLM or your own gateway. The provider fills in the base URL and the auth: a bearer token from `{{openaiApiKey}}`, `{{openrouterApiKey}}` or `{{groqApiKey}}`, `x-api-key` from `{{anthropicApiKey}}`, and no auth for the local servers. Set the key in an environment, mark it secret, and it never lands in the YAML; if the variable is not set, Kurlo says so before sending. A key typed into the Auth tab is kept encrypted on this computer, so a workspace opened on another computer asks for it again. The URL is the provider's base URL: Kurlo adds `/chat/completions` to it, or `/messages` for Anthropic, and shows the full address under the URL field, with the added path highlighted. A URL that already ends with that path is used as it is, and a query string such as `?api-version=` stays at the end. The model is the name the provider knows it by, such as `gpt-4o-mini` or `llama3.2`: when you open the box, Kurlo reads the provider's `/models` list so you can pick one, and you can always type a name instead. **Kurlo connection** uses the default connection from [Settings → AI](https://kurlo.dev/docs/guides/settings/ai/#ai) instead of a URL and an Auth tab: Kurlo adds the connection's address and key when it sends, so the key never reaches the request, its history or the YAML. The model is the one chosen for that connection, so the request bar shows the connection and its model instead of a model field; change either in Settings → AI and open requests follow at once. **Open Settings → AI** in the model box, or a click on the connection in the request bar, opens Settings → AI on the **Kurlo agent** part with the connections and their models. The Auth tab is not sent. Saved in a shared collection, the request uses each teammate's own default connection. To use another connection than the default, choose it in **Settings → Connection**; the request file keeps only the connection's id, and a teammate without that connection sees **Removed connection** and can pick one of their own. The **Prompt** tab holds the system prompt and the prompt; `{{variables}}` work in both. The prompt field grows with its text and scrolls once it fills the tab; in a short request panel it shrinks to the space left and shows a scroll bar only when the text does not fit. The prompt and every chat message take up to 200,000 characters (about 50,000 tokens) and the system prompt up to 50,000; a counter shows up next to the label as you get close. **Settings** holds the model parameters (temperature, max tokens, top P, streaming, thinking for Anthropic models), how long to wait for a silent provider, and the SSL and proxy settings a local model or a company proxy may need. Auth and Headers are the usual ones: the provider presets fill Auth in, and Headers is there for gateways that want extra ones, such as OpenRouter's `HTTP-Referer`. **Send** starts a new conversation with the saved prompt, so the request behaves the same every time you open it. The answer streams in as it is written: - **Text** builds up word by word, and **thinking** sits in a collapsed block above it when the model shares it. - **Tool calls** are cards with the tool's name, the server it came from, its call ID and its arguments, which grow while the model writes them. The result, or the tool's error, appears under the call. - The status line shows the **time to the first token**, the **speed** in tokens per second and the **tokens** in and out, with cache reads; hover it for the breakdown per type. - The **stop reason** is shown under the answer. An answer cut off by the token limit says so and offers to raise the limit and send again, and an error in the middle of a stream, which arrives with HTTP 200, is shown where the stream stopped, below the part that did arrive. Answers are rendered as Markdown: headings, lists, tables, code blocks with a **Copy** button, and links, which open in your browser. Images the model puts in its answer as a `data:` URL are shown; remote images stay links, so an answer cannot make Kurlo fetch a URL on its own. To continue the conversation, type in the field under the answer and press `Enter`; `Shift+Enter` starts a new line. Kurlo sends the earlier messages, the tool calls and their results along with it. The system prompt and the settings apply to every message; the **Prompt** is only the first one. **New chat** in the status line clears the conversation, and **Send** starts a new one from the prompt. The conversation lives only while the request is open; each send is in History. **Raw** shows, for each model call, the URL, the request body Kurlo sent and the stream exactly as it arrived. Steps are folded except the last one, and a body over 20,000 characters shows its start with **Show all**, so a long conversation stays quick to open. Raw keeps the bodies of the latest send only. **Tests** shows the results of the request's test scripts, which run once after the last step. `pm.response.llm()` gives them the answer in one shape for every provider, so a test reads the same for OpenAI and Anthropic: ```javascript const llm = pm.response.llm(); pm.test("asks for the weather", () => { pm.expect(llm.toolCalls[0].name).to.equal("get_weather"); pm.expect(llm.toolCalls[0].input.city).to.equal("Lisbon"); }); pm.test("stays short", () => pm.expect(llm.usage.output).to.be.below(300)); pm.test("answers fast", () => pm.expect(llm.timing.firstToken).to.be.below(800)); ``` ### Tools from MCP servers The **Tools** tab lists the MCP requests saved in the workspace. Tick one and the model gets that server's tools. When it calls one, Kurlo runs the call with the MCP request's URL, auth and headers, sends the result back and asks the model again, until it answers without calling a tool or the **step limit** is reached (8 by default, 50 at most). Each step is visible in the conversation, and a tool that fails is reported to the model as an error so it can recover. With no MCP requests in the workspace yet, **New MCP request** opens one as a draft: save it to a collection to offer it to the model, or close it and nothing is left behind. Tool names the providers do not accept, such as `files.read`, are renamed to `files_read`, and two servers with a tool of the same name get the server's name in front. ### Kurlo tools Tick **Kurlo tools** at the top of the **Tools** tab to give the model Kurlo's own tools for this workspace, the same ones the [agent](https://kurlo.dev/docs/guides/agent/) uses, called inside the app without a network server. The model can list and read requests, collections, environments and history, run saved requests and collections and send one-off `GET`, `HEAD` and `OPTIONS` calls, all in the environment active in the top bar. An AI request has no one to approve a change, so calls that would send `POST`, `PUT`, `PATCH` or `DELETE`, contact another server, or change the workspace files are declined and the model is told why. Use the Kurlo agent for those. Kurlo tools work together with MCP servers ticked below them and count toward the same step limit. ### Good to know - **Stop after silence** in Settings is the only timeout: the stream is stopped when no data has arrived for that long (five minutes when it is not set), so a long answer that keeps streaming is never cut off. - Anthropic thinking blocks, with their signatures, are sent back unchanged in later steps, as the API requires during tool use. - For OpenAI-compatible streams Kurlo asks for usage with `stream_options`. A server that ignores it shows no token counts. - Not in this release: the OpenAI Responses API, Gemini's own API, images and files in the prompt, prices, and running AI requests with `kurlo run`. # Import and export by protocol Source: https://kurlo.dev/docs/guides/request-types/portability/ > Check which request types can move between tools. ## Import and export notes | Format | Import into Kurlo | Export from Kurlo | |--------|-------------------|-------------------| | [Postman v3 Native Git folder](https://kurlo.dev/docs/guides/import-export/postman/#postman-v3-folders) | HTTP, GraphQL, gRPC, WebSocket, Socket.IO, and MCP over HTTP | [HTTP, GraphQL, and native gRPC](https://kurlo.dev/docs/guides/import-export/postman/#export-to-postman-v3). SSE as HTTP streaming | | [Postman v2 JSON](https://kurlo.dev/docs/guides/import-export/postman/) | v2.0 and v2.1. HTTP and GraphQL, with additional request metadata in files exported by Kurlo | v2.1 JSON. HTTP, GraphQL and SSE using HTTP fields. Kurlo can reconstruct gRPC, WebSocket, and Socket.IO from its own export metadata | | [Insomnia v4 JSON](https://kurlo.dev/docs/getting-started/migrating/insomnia/) | HTTP, GraphQL, gRPC, WebSocket, and Socket.IO | v4 workspace JSON, including gRPC, WebSocket and Socket.IO request resources | | [OpenAPI / Swagger](https://kurlo.dev/docs/guides/import-export/openapi/) | HTTP and SSE operations | HTTP and SSE as OpenAPI 3.0 or Swagger 2.0 | | [Bruno / OpenCollection](https://kurlo.dev/docs/guides/import-export/bruno/) | HTTP, GraphQL, gRPC, WebSocket, and Socket.IO | OpenCollection YAML with HTTP, GraphQL, gRPC, WebSocket, and Socket.IO request records | | [Kurlo all-data backup](https://kurlo.dev/docs/guides/backup-recovery/) | All Kurlo request types | All Kurlo request types | | [Kurlo Git/YAML workspace](https://kurlo.dev/docs/reference/kurlo-yaml-format/) | All Kurlo request types | All Kurlo request types | Use Postman v3 to move native gRPC requests between Kurlo and Postman. Kurlo can import a v3 folder or a single `*.request.yaml` file. The v2.1 JSON export stores gRPC-specific fields in `x-kurlo` for re-import into Kurlo. A Postman v3, OpenAPI, or Swagger export reports how many requests it skipped. Use a Kurlo workspace or backup to preserve Kurlo-specific fields across every request type. # Authentication Source: https://kurlo.dev/docs/guides/authentication/ > Configure Bearer, Basic, Digest, NTLM, API Key, JWT Bearer, OAuth 1.0, OAuth 2.0, and AWS Signature v4 auth. Auth is configured per request on the **Auth** tab. Collections can also define default auth; requests set to **Inherit auth** use the collection default, while requests with an explicit auth type override it. For certificate-based authentication, see [Client certificates (mTLS)](https://kurlo.dev/docs/guides/request-settings/client-certificates/). # Bearer token Source: https://kurlo.dev/docs/guides/authentication/bearer/ > Send an access token directly or read it from an environment. The simplest case: paste the token, Kurlo sends `Authorization: Bearer `. Use `{{tokenVar}}` to pull from an environment. Every field on the Auth tab, at request and collection level, takes `{{variables}}`: type `{{` to pick one from the active environment, and an undefined variable is underlined in red. A secret field shows a value made only of variables, such as `{{token}}`, as plain text, and hides anything else behind dots. # Basic Auth Source: https://kurlo.dev/docs/guides/authentication/basic/ > Send a username and password with HTTP Basic authentication. Username + password. Kurlo base64-encodes for you. # Digest Auth Source: https://kurlo.dev/docs/guides/authentication/digest/ > Authenticate against a server's Digest challenge. Kurlo sends the first request unauthenticated, parses the `WWW-Authenticate` header, and replays with the digest. No configuration beyond username/password. Supported algorithms (RFC 7616): `MD5`, `SHA-256`, `SHA-512-256`, and their `-sess` session variants. Kurlo echoes the algorithm token back exactly as the server named it. Both `qop=auth` and `qop=auth-int` work — when a server offers both, plain `auth` is used so the body never has to be buffered. Servers that advertise `userhash=true` get a hashed username. A challenge with no `qop` falls back to the legacy RFC 2069 form. `qop=auth-int` signs the entity body, so the whole body has to be hashed before the request goes out; a body over 32 MB, or one that cannot be re-read, fails with a clear message instead. # NTLM Source: https://kurlo.dev/docs/guides/authentication/ntlm/ > Authenticate to a server using Windows domain credentials. Choose **NTLM** in the Auth tab of an HTTP, GraphQL or SSE request. Enter a username such as `DOMAIN\user` or `user@example.com`, then enter the password or reference an environment variable such as `{{ntlmPassword}}`. Kurlo negotiates NTLMv2 over one HTTP/1.1 connection and keeps the credentials scoped to the request origin. # API key Source: https://kurlo.dev/docs/guides/authentication/api-key/ > Attach a key to a request header or query parameter. - **In header** — choose the header name (`X-API-Key`, `apikey`, etc.). - **In query string** — appended on send, not stored in the URL. # JWT Bearer Source: https://kurlo.dev/docs/guides/authentication/jwt/ > Sign a new token at send time with a secret or private key. Choose **JWT Bearer** when an API expects a JSON Web Token that you sign yourself, for example a service-to-service call or a gateway that checks a shared secret. Kurlo signs a fresh token on every send, so you no longer paste a token that expires. - **Algorithm**: `HS256`, `HS384`, `HS512` with a shared **Secret**, or `RS256`–`RS512`, `PS256`–`PS512`, `ES256`–`ES512` with a **Private key** in PEM form (PKCS#1, PKCS#8 or SEC1). Tick **Secret is base64-encoded** when the secret you were given is base64. Both fields accept a `{{variable}}`, so the key can stay in a secret environment variable. - **Payload**: the claims as a JSON object, such as `{ "sub": "{{userId}}", "role": "admin" }`. `{{variables}}` and [dynamic variables](https://kurlo.dev/docs/guides/environments/dynamic-variables/) are resolved on send. - **Expires in, seconds** adds `iat` (now) and `exp` (now plus the lifetime) unless the payload already sets them. Leave it empty to send the payload as written. - **Add token to**: the `Authorization` header with a **Header prefix** (`Bearer` by default), or a **Query string** parameter (`token` by default). gRPC requests send it as `authorization` metadata. - **Advanced → Extra header fields** adds JSON fields to the token header, such as `{ "kid": "key-1" }`. `alg` always follows the chosen algorithm. **Preview token** signs a token the way the next send would: with the active environment's variables, dynamic variables and `iat`/`exp` filled in. It shows the encoded token, which **Copy token** puts on the clipboard for use in another tool, and below it the header and the claims that ended up in it. A token without `exp` is marked **No expiry**. A payload that is not valid JSON, or a key that does not match the algorithm, stops the send with the reason in the response panel. The same signing runs in `kurlo run` and `kurlo mcp`. Generated code and **Copy as cURL** cannot sign, so they write a `{{jwtToken}}` placeholder; replace it with a token from **Preview token**. Postman's JWT Bearer auth imports and exports with every setting except **Expires in**, which Postman does not have. A k6 load test sends these requests without auth and says so in the export warnings. # OAuth 2.0 Source: https://kurlo.dev/docs/guides/authentication/oauth2/ > Choose a grant type, fetch a token, and configure refresh. Kurlo supports four grant types, picked from **Grant type**: - **Client credentials** — enter the token URL, client ID, client secret, and optional scope, then click **Get access token**. - **Authorization code** — enter the authorization URL, token URL, client ID, optional client secret, and scope, then click **Authorize in browser**. Kurlo opens the system browser and receives the callback through a temporary loopback listener on `127.0.0.1`. - **Device code** (RFC 8628) — enter the device authorization URL, token URL, and client ID, then click **Start device sign-in**. Kurlo shows the user code, opens the verification page, and polls the token endpoint until you approve. It honours the server's `interval` and backs off on `slow_down`. This is the grant to use where a loopback redirect cannot work — a headless machine or a remote session. - **Password** — the RFC 6749 resource-owner grant: token URL, username, and password. Legacy by design, but still required by some internal token endpoints. For Authorization Code, **Use PKCE** is enabled as the recommended option for public clients. Kurlo uses S256 PKCE. A client secret is optional when PKCE is used. **Client authentication** selects how the client identifies itself at the token endpoint: - **Send as Basic auth header** — HTTP Basic, the RFC 6749 default when a secret is set. - **Send client credentials in body** — `client_id` + `client_secret` as form fields (`client_secret_post`), which some providers require instead. - **Client secret JWT** — an RFC 7523 assertion signed with the client secret (HS256). - **Private key JWT** — an RFC 7523 assertion signed with an RSA or ECDSA private key. Paste the key in PEM form (PKCS#1, PKCS#8, or SEC1); the algorithm is inferred from the key unless you set it. The key field accepts a `{{variable}}`, so it can live in workspace secrets rather than in the YAML. For both assertion methods the audience defaults to the token URL, which is what providers expect; override it if yours differs. Assertions are minted fresh per request with a random `jti` and a five-minute lifetime. **Audience** sends an `audience` parameter alongside the token request. It is not part of RFC 6749 but Auth0 requires it and several other providers accept it. The acquired `access_token` is injected as `Authorization: Bearer ...` on send. If the provider returns a refresh token, Kurlo exposes **Refresh token** and automatically refreshes an expired access token before sending a request. # OAuth 1.0 Source: https://kurlo.dev/docs/guides/authentication/oauth1/ > Sign OAuth 1.0 requests with consumer and token credentials. Sign each request with OAuth 1.0a ([RFC 5849](https://www.rfc-editor.org/rfc/rfc5849)), the scheme of older APIs such as Twitter/X v1.1, Trello, Flickr or Jira Server. - **Consumer key** and **consumer secret**, plus the **access token** and **token secret** when you act for a user. Use `{{variables}}` for the secrets. - **Signature method**: `HMAC-SHA1` (the default), `HMAC-SHA256`, `HMAC-SHA512`, `RSA-SHA1`, `RSA-SHA256`, `RSA-SHA512` or `PLAINTEXT`. The RSA methods take a PEM private key instead of the two secrets. - **Add parameters to**: the `Authorization: OAuth …` header (the default), the query string, or the body. The body works only with a form-urlencoded body, or with no body, which then becomes one. Kurlo generates a fresh **timestamp** and **nonce** on every send and signs the method, the URL and its query, and the fields of a form-urlencoded body. OAuth 1.0 reads the body into memory to sign it, so it refuses a body larger than 32 MB. **Advanced** holds the realm, the callback URL and the verifier of the three-legged flow, the version, fixed timestamp and nonce values for debugging a signature, **Include body hash** (`oauth_body_hash` for bodies that are not form-urlencoded) and **Sign empty parameters**. # AWS Signature v4 Source: https://kurlo.dev/docs/guides/authentication/aws-sigv4/ > Sign requests with AWS credentials, region, and service. Sign requests to AWS APIs (S3, API Gateway, etc.). - Access key + secret key (use environment variables, never hard-code). - Service name (e.g. `s3`, `execute-api`). - Region (e.g. `us-east-1`). Kurlo computes the canonical request, derives the signing key, and adds `Authorization`, `x-amz-date`, and `x-amz-content-sha256` headers automatically. A file body is hashed as it is read, without loading it into memory, so large S3 uploads sign without a size limit. **Session token** covers temporary credentials from STS, an assumed role, or AWS SSO. Kurlo sends it as `x-amz-security-token` and includes it in `SignedHeaders`, which is what AWS requires — a token that is sent but not signed is rejected. # Inheriting auth Source: https://kurlo.dev/docs/guides/authentication/inheritance/ > Set collection or folder defaults and understand request overrides. A request set to **Inherit auth** uses the auth of the nearest enclosing folder that sets one, or the collection's when none does. This is useful when an entire collection, or one part of it, talks to the same API. See [Folder defaults](https://kurlo.dev/docs/guides/collection-defaults/folders/). Postman and Bruno folders that have their own auth keep it as folder auth. Insomnia folder auth is flattened into request-level or collection-level settings where Kurlo can represent it. After a large import, spot-check the Auth tab for the most sensitive requests. ## The Auth tab wins over a hand-written header Auth is applied after your header rows, so a request that has both bearer auth configured **and** an `Authorization` header typed by hand sends the one from the Auth tab. The same goes for whatever header name an API key is configured under. That precedence has not changed, but Kurlo now says so: the response panel names the header that was replaced, instead of leaving you looking at a row that never went out. To send your own header, set Auth to **No auth**. ## Secrets and storage Auth fields in Kurlo's local profile are encrypted at rest with AES-256-GCM. Kurlo writes the key to the OS credential store when available and keeps a `0600` recovery-key file in its app-data directory. In Git-backed workspaces, shared YAML receives `{{kurloSecret:...}}` placeholders while the real values remain in the encrypted local profile. Never paste secrets into request URLs or committed YAML. Prefer secret environment variables or local auth fields. # Per-request settings Source: https://kurlo.dev/docs/guides/request-settings/ > Configure transport, client certificates, timeouts, proxies, cookies, and reconnect behavior for individual requests. Open the request's **Settings** tab to override its defaults. The available options depend on the request type. Every setting on this page is **per-request** — changing it on `Get user` doesn't affect `Get billing`. Settings travel with the request when you export, duplicate, or commit it to Git. App-wide preferences (autosave, theme, shortcuts, updates) live in a separate Settings modal opened from the gear at the bottom of the activity rail. See [App settings](https://kurlo.dev/docs/guides/settings/) for that surface. # HTTP transport Source: https://kurlo.dev/docs/guides/request-settings/http-transport/ > Configure HTTP version, redirects, and server certificate verification. ## HTTP version Choose how Kurlo negotiates the protocol: | Value | Behaviour | |-------|-----------| | `Auto` *(default)* | ALPN negotiates HTTP/2 if both ends support it, otherwise HTTP/1.1. | | `1.1` | Force HTTP/1.1. Useful when an upstream proxy mishandles HTTP/2. | | `2` | Require HTTP/2 over TLS. Connect fails if the server doesn't speak it. | HTTP/3 is not yet supported. ## Redirect policy By default Kurlo follows up to **10 redirects**. You can change this and decide what to do with them: - **Follow redirects** — toggle. Off means a 3xx returns the redirect response itself, with the `Location` header visible in the Headers tab. - **Max redirects** — integer cap. Set to `0` to behave like *Follow off*. - **Preserve original method** — when on, a 301/302 redirect from `POST` stays `POST` instead of becoming `GET`. RFC 7231 allows the agent to switch the method; this toggle forces the safer "preserve" behaviour. - **Preserve Authorization header** — by default, redirecting to a different host **drops** the `Authorization` header to avoid leaking credentials. Turn this on if you're following redirects within a trusted multi-host system. Same-host redirects always keep the header. - **Remove Referer when downgrading** — drop the `Referer` header when redirecting from `https://` to `http://`. Matches browser behaviour. ## TLS / SSL verification The toggle **Enable SSL certificate verification** is on by default. Turning it off makes Kurlo accept any certificate the server presents, including self-signed and expired ones. When you disable it, Kurlo shows a one-time confirmation dialog explaining the risk. Re-enabling is one click in the same place. :::caution Disabling SSL verification opens you to MITM attacks on that request. Only use it against a server you control or a known-good staging endpoint. ::: For corporate root CAs, the cleaner fix is to install the CA into your system trust store — Kurlo uses the OS trust roots, so once the CA is trusted system-wide it works in Kurlo too. # Client certificates (mTLS) Source: https://kurlo.dev/docs/guides/request-settings/client-certificates/ > Use PEM or PKCS#12 client certificates with HTTP and gRPC. ## Client certificate (mutual TLS) For servers that require **mutual TLS**, open **Settings → Client certificate (mTLS)** on an HTTP, SSE, MCP, or gRPC request. A gRPC call sends the certificate when it uses TLS. For GraphQL requests, set the certificate at collection level. - **Certificate (PEM/PFX/P12)** — a PEM certificate or a PKCS#12 container (`.pfx` or `.p12`). A PKCS#12 container includes the private key and can include the certificate chain. - **Private key (optional)** — a separate PEM key file. Leave it blank for PFX/P12 or when the key is in the same file as the certificate (a combined PEM). - **Passphrase** — the PFX/P12 container password or the password for an encrypted PEM key. It accepts a `{{variable}}`, so you can point it at a workspace secret instead of storing it in the YAML. After replacing a certificate or key file, send the request again to use the updated certificate. You do not need to restart Kurlo. To share a certificate, open the collection's **⋯ → Settings** in the sidebar. Select the **Proxy** tab and set **Client certificate (mTLS)**. For manual saving, click **Save** after editing the request or collection settings. A missing file, a mismatched certificate/key pair, or a wrong passphrase fails the request before it dials, with a message that says which. Kurlo supports password-protected and unprotected PFX/P12 containers, and PEM keys including the legacy openssl encrypted format; PKCS#8-encrypted keys need converting first (`openssl pkcs8 -in key.pem -out key.dec.pem`). # Timeouts and scripts Source: https://kurlo.dev/docs/guides/request-settings/timeouts-and-scripts/ ## Timeout **Request timeout (ms)** caps the total time from connection start to body fully read. Default: **30 000 ms** (30 seconds). Set to `0` to wait as long as the server takes — useful for **Send and download** of a large file. The timeout includes: - DNS resolution - TCP connect / TLS handshake - Request body upload (for `POST` / `PUT`) - Server processing time - Full response body read If the timeout fires, the response shows a friendly error: *"The request timed out after 30 s. Check the URL and try again."* The duration counter still shows how long Kurlo actually waited. ## Script settings **Script timeout (ms)** caps how long a single pre-request or test script may run. Leave it at `0` for the default **2 000 ms**; raise it for a heavy assertion suite or a signing step. The ceiling is 60 000 ms, so a runaway loop can never wedge a send. **Allow pm.sendRequest** lets this request's scripts make their own HTTP calls — fetching a token before the send, or chaining setup. It is **off** by default: the script sandbox has no network access unless you ask for it. See [`pm.sendRequest`](https://kurlo.dev/docs/reference/scripting-api/send-request/) for its limits. Both live under *Collection settings → Settings* as well, and a request that has not touched them inherits the collection's value — in the app and in [`kurlo run`](https://kurlo.dev/docs/guides/cli-runner/) alike. `--script-timeout` and `--allow-send-request` override the whole run. # Cookies and URL encoding Source: https://kurlo.dev/docs/guides/request-settings/cookies-and-encoding/ ## Cookie jar The toggle **Use the cookie jar** controls whether `Set-Cookie` responses are stored and replayed: - **On** (default) — cookies sent in responses are added to the per-workspace cookie jar. On subsequent requests to the same domain, matching cookies are attached automatically. - **Off** — Kurlo neither stores nor sends jar cookies for this request. You can still set cookies manually via the `Cookie` header. The jar is shared across all requests in a workspace. View / edit it via the cookie icon at the bottom of the activity rail. See [Cookies](https://kurlo.dev/docs/guides/cookies/) for manual cookie editing, matching rules, and backup behavior. ## URL encoding **Encode URL automatically** (on by default) percent-encodes characters in path segments and query values when Kurlo sends the request. Examples: - A space in a query value (`q=hello world`) becomes `q=hello%20world`. - Cyrillic / emoji / other non-ASCII characters are encoded per RFC 3986. Turn this off if your server uses non-standard encoding rules — Kurlo will then transmit your URL byte-for-byte as you typed it. # Proxy and browser emulation Source: https://kurlo.dev/docs/guides/request-settings/proxy-and-browser/ ## Proxy **HTTP proxy** accepts a complete HTTP, HTTPS, or SOCKS5 proxy URL. A non-empty request value overrides both the collection proxy and the app-wide proxy. Leave the field untouched to inherit the collection setting. If no collection URL applies, Kurlo uses **Settings -> Proxy**. Clearing the field after editing it creates an empty request override, skips the collection value, and falls back to the app-wide setting. See [Proxy configuration](https://kurlo.dev/docs/guides/proxy/) for the complete precedence and bypass rules. ## Browser security emulation Use these controls to add a browser-like origin and user agent, enforce CORS preflights and response checks, or block URLs rejected by a page's CSP `connect-src`. See [Browser security emulation](https://kurlo.dev/docs/guides/browser-security/) for credentials mode, same-origin behavior, supported CSP sources, and protocol differences. # Streaming request settings Source: https://kurlo.dev/docs/guides/request-settings/streaming/ > Configure reconnect behavior for WebSocket, Socket.IO, and SSE. ## WebSocket / Socket.IO–specific settings For `ws://` / `wss://` and Socket.IO requests, extra knobs appear: - **Handshake timeout (ms)** — how long to wait for the connection handshake. `0` uses the default of 30 seconds. - **Reconnect attempts** — number of automatic reconnect attempts after an abnormal close. `0` = never reconnect. Default `0`. - **Reconnect interval (ms)** — delay between reconnect attempts. Default `5 000`. - **Max message size (MB)** — read limit per message. Default `10 MB`. Reduce if you're testing constrained servers; increase if you legitimately stream larger messages. - **Keep-alive interval (ms)** — how often to ping the server to hold the connection open. `0` uses the default; `-1` stops pinging entirely, which is what you want against a server that treats an unsolicited ping as a protocol error. ## SSE-specific settings A request whose method is set to **SSE** gets two more: - **Reconnect automatically** — on by default, matching a browser `EventSource`: the stream resumes from the last event id it saw. Turn it off to watch a failing stream stop instead of retrying, which is what you usually want while debugging the server end. - **Reconnect interval (ms)** — how long to wait before reconnecting. `0` follows the interval the server sends in its `retry:` field. gRPC requests also show gRPC-specific settings: TLS, reflection, server name, client certificate, default-value inclusion, and max response message size. See [Request types](https://kurlo.dev/docs/guides/request-types/) for how the protocol-specific editors differ. # Reset request settings Source: https://kurlo.dev/docs/guides/request-settings/defaults/ ## Reset to defaults Click **Reset** at the top of the request Settings tab to restore Kurlo's built-in request values and clear collection override markers. Collection defaults can then apply again when the request is sent. ## Where these settings live in your data Per-request settings are saved alongside the request. Local profile state is stored in encrypted `requests.json`; folder/Git workspaces store shareable settings in YAML. Settings are exported where the target format can represent them and preserved by Kurlo/OpenCollection round-trips. # Response viewer Source: https://kurlo.dev/docs/guides/response-viewer/ > Inspect status, headers, and test results, search or filter the body, and compare responses. The response appears beside the request editor when the window has room, or below it in a narrower window. Use the [response layout shortcut](https://kurlo.dev/docs/reference/keyboard-shortcuts/global/) to switch layouts. The status bar shows response metadata, and the tabs show the body, headers, and script results when available. # Response status Source: https://kurlo.dev/docs/guides/response-viewer/inspect/ ## The status bar The thin row at the top of the response panel summarizes the result: - **HTTP status** — `200 OK`, `404 Not Found`, etc. Colour-coded by class: green for 2xx, yellow for 3xx, orange for 4xx, red for 5xx and transport errors. - **Duration** — total time from request build to body fully read, in milliseconds. Hover the duration pill to see a timing breakdown (DNS, TCP connect, TLS handshake, time-to-first-byte, body read). - **Size** — uncompressed body size. For [paged responses](https://kurlo.dev/docs/guides/response-viewer/large-responses/), this is the size of the whole payload. Click **Save to file** (the download arrow) to write the body to a file. Click **Copy response** to copy it to the clipboard. # Reading the response body Source: https://kurlo.dev/docs/guides/response-viewer/body/ ## Body view The body view auto-detects how to render the payload: - **JSON** — syntax-highlighted, two-space indent, line numbers in the gutter. Folding is enabled if your response is deeply nested. - **HTML** / **XML** — syntax-highlighted with line numbers. - **Plain text / unknown** — rendered verbatim. No reformatting. - **Binary or `application/octet-stream`** — Kurlo shows the detected type and size. Click **Preview** for a supported format or **Save to file** to keep the body. - **Server-Sent Events (`text/event-stream`)** — Kurlo switches automatically to the SSE panel with streamed event rows. - **WebSocket / Socket.IO / gRPC** — realtime and RPC requests use dedicated response surfaces for frames, events, metadata, status, and logs. # Search and filter a response Source: https://kurlo.dev/docs/guides/response-viewer/search-and-filter/ ## Searching the body Click the magnifying glass at the right end of the status row (or press the search shortcut configured in *Settings → Shortcuts*) to open the inline search bar. As you type, matches highlight in place and the counter shows `current/total`: - `↓` / `↑` — jump to next / previous match - `Enter` / `Shift+Enter` — same as next / previous - `Esc` — close the search bar without clearing the response Search is case-insensitive. For [paged responses](https://kurlo.dev/docs/guides/response-viewer/large-responses/), it searches the visible page. Switch pages to search the rest. ## Filtering a JSON response For a JSON response, the funnel button next to search opens a filter bar above the body. Type a [JSONPath](https://www.rfc-editor.org/rfc/rfc9535) expression and the body shows only what it selects; the counter on the right shows how many values matched. | Filter | Shows | |---|---| | `$.data.user.email` | One value | | `$.items[*].id` or `.items[].id` | The `id` of every item | | `$.items[0]`, `$.items[-1]`, `$.items[1:3]` | By position, from the end, or a range | | `$..price` | Every `price`, at any depth | | `$.items[?(@.status == 'paid' && @.total > 20)]` | Items that match a condition | - A path that can only pick one value, such as `$.meta.page`, shows that value. Any other path shows an array of the matches. - A path that starts with a dot is read jq-style: `.items[].id` is the same as `$.items[*].id`. Pipes and jq functions are not supported. - Conditions compare with `==`, `!=`, `<`, `<=`, `>`, `>=` and combine with `&&`, `||` and `!`. `?(@.isbn)` keeps items that have the field. - If the expression has a mistake, the body stays unfiltered and the bar says what is wrong and where. - The filter applies once you pause typing, or at once when you press `Enter`, so a large body is not filtered again on every keystroke. **Copy** always uses what is in the bar. - Search, **Copy** and paging work on the filtered result. `Esc` or the **×** closes the filter and shows the whole body again. - Numbers larger than JavaScript can hold exactly, such as long numeric IDs, can lose their last digits in the filtered view. The unfiltered body shows them as received. # Large responses Source: https://kurlo.dev/docs/guides/response-viewer/large-responses/ ## Paging through large responses Bodies whose reported response size is over **10 MB** are rendered in ~512 KiB pages so the editor stays responsive. The page bar appears above the body when paging is active: > Large response preview · Page 2 / 6 · `←` `2/6` `→` Page navigation buttons (or the keyboard shortcuts mapped to "next/prev response page" in Settings) move you through the chunks. The response itself is held intact in memory — paging only affects rendering. ## Truncation If the server returns more than **100 MB**, Kurlo stops reading after the first 100 MB and marks the response with a banner such as *"response truncated — showing 100 MB of 450 MB"*. The status code and headers are unaffected. The response-panel **Save to file** action and **Send and download** currently write the body Kurlo retained, so they do not recover bytes beyond this 100 MB cap. # Headers and timeline Source: https://kurlo.dev/docs/guides/response-viewer/timeline/ ## Headers view Switch to the *Headers* tab to see the response headers exactly as the server sent them. They're listed in the order the server emitted them — for `Set-Cookie` and other headers that can repeat, each occurrence has its own row. Hover any value to reveal a copy button. The header table is plain text — you can also select-and-copy with your usual editor shortcuts. ## Timeline view The *Timeline* tab appears once a response carries connection details. It answers "where did the time go, and what did Kurlo actually send?". - **Timeline** — connection requested, DNS lookup, TCP connect, TLS handshake, request sent, and first response byte, each stamped in milliseconds from the start of the send. - **Connection** — whether the connection was newly opened or reused from the pool, the local and remote addresses, every resolved address, and the negotiated TLS version, cipher suite, ALPN protocol, and SNI server name. - **Request** — the request line and headers as they went on the wire, after auth, cookie jar, and redirect handling. A redirect chain shows one block per hop, so you can see exactly what was re-sent and what was dropped. Secret environment values are masked here the same way they are in script logs, so the panel is safe to screenshot. A failed request keeps its timeline: when a connection times out or a TLS handshake fails, the last event tells you how far it got. # Compare and save responses Source: https://kurlo.dev/docs/guides/response-viewer/diff/ ## Diff view The *Diff* tab appears the second time you send the same request. It compares the previous response body with the current one: - Removed lines are red, added lines are green, and both original line numbers are kept. - Long unchanged runs collapse to a `… unchanged lines` marker — *Show all lines* expands them. - *Clear baseline* forgets the previous response and hides the tab until the next send. Baselines are per-request and live in memory only; they are never written to the workspace and are dropped when Kurlo restarts. You can also diff against a **saved example** instead of the previous response. That is what stops an example from going stale: an endpoint that no longer matches the contract shows up as a diff rather than passing unnoticed. If the example the baseline pointed at is deleted, it falls back to the previous response. See [Response examples](https://kurlo.dev/docs/guides/examples/). ## Saving a response as an example **Save as example** keeps the response — status, headers and body — next to the request that produced it, as a file in your workspace rather than something only you can see. Secrets are redacted on capture. Examples are what the [mock server](https://kurlo.dev/docs/guides/mock-server/) replays. See [Response examples](https://kurlo.dev/docs/guides/examples/). # Test results Source: https://kurlo.dev/docs/guides/response-viewer/tests/ ## Scripts view (test results) The *Scripts* tab is enabled whenever a request had a pre-request or test script attached. It groups results into blocks: - **Pre-request** — outcome of the pre-request script and any logs emitted via `pm.log(...)`. If the pre-request script errored, the request was not sent. - **Tests** — each `pm.test(name, assertion)` is rendered as a green tick or red cross with the assertion name. The header shows a summary like `4/5 passed`. - **Logs** — anything emitted with `pm.log(...)` from inside the test script. If a request had no scripts attached, this tab shows *"No scripts ran for this request."* For the full script API, see the [Scripting API reference](https://kurlo.dev/docs/reference/scripting-api/). ## Common gotchas - **"This endpoint returned an SSE stream."** Your request used a regular method but the server replied with `text/event-stream`. Switch the request to SSE mode and press *Connect*. - **Binary download with the wrong Content-Type.** Some servers send `application/json` for what's actually a `.pdf` or `.zip`. Kurlo checks the bytes to detect the response type. Use **Save to file** to keep the binary body. - **"Response body is empty"** with a non-2xx status. Some APIs return a status code but no body (e.g. 204 No Content). This is shown as an empty body view, not an error. - **Slow rendering on huge JSON.** If your response is over a few MB of densely nested JSON, switch the body view to *Raw* in the editor settings to skip syntax highlighting. # Binary responses and previews Source: https://kurlo.dev/docs/guides/response-viewer/preview/ ## Binary responses A body that is not text — an image, a PDF, an archive, a font — is not rendered as text. Kurlo inspects the actual bytes rather than trusting `Content-Type`, so a payload mislabelled as `text/html` is still recognised, and shows what it found (the sniffed type and the size) with buttons to open the [preview](https://kurlo.dev/docs/guides/response-viewer/preview/#preview) or save the body to a file. ## Preview A **Preview** tab appears next to Body when the response is something worth rendering: - **Images** (PNG, JPEG, GIF, WebP, BMP, AVIF, SVG, ICO) render on a checkerboard with their dimensions and size. An image response opens on this tab automatically, since the raw bytes are meaningless in the text view. An image served as `application/octet-stream` is still detected by sniffing its contents. - **HTML** renders in a fully sandboxed frame. Scripts do not run and the page cannot reach the network or the app around it, so the preview is safe for a response from any server. It is a rendering aid, not a browser. Images travel to the viewer through a separate lossless channel, because the response body crosses to the interface as text and binary bytes would not survive intact. Images over 16 MB, and any truncated response, are not previewed. ## Related - [Per-request settings](https://kurlo.dev/docs/guides/request-settings/) — `httpVersion`, redirect policy, timeout, cookie jar - [Request types](https://kurlo.dev/docs/guides/request-types/) — GraphQL, SSE, WebSocket, Socket.IO, and gRPC response surfaces - [Request history](https://kurlo.dev/docs/guides/history/) — find recent requests and responses, with [retention and body limits](https://kurlo.dev/docs/guides/history/retention/) - [Code snippets](https://kurlo.dev/docs/guides/code-generation/) — copy the request that produced this response in any supported language - [Response examples](https://kurlo.dev/docs/guides/examples/) — keep a response as a reviewable file, and diff against it later - [Mock server](https://kurlo.dev/docs/guides/mock-server/) — serve those examples over HTTP # Request history Source: https://kurlo.dev/docs/guides/history/ > Find recent requests and sessions across workspaces, inspect recorded responses, and reopen or save requests. **Request history** records recent sends and connection attempts from the desktop app. It is stored locally and encrypted alongside the request store. The 14-day and 1,000-entry limits apply across workspaces in the profile. # Find a request in history Source: https://kurlo.dev/docs/guides/history/find/ ## Opening history In the sidebar, switch from *Collections* to *History* via the toggle at the top. The list groups entries by **day**: ``` Today 10:42 GET 200 /v1/users 10:41 POST 201 /v1/users 10:38 GET 404 /v1/users/missing Yesterday 18:11 GET 500 /v1/billing … ``` Each row shows the time, method, status, and URL. The status is color-coded with the same palette as the response panel (green 2xx, orange 4xx, red 5xx). Toggle a day open or closed with the chevron. Days collapse independently — you can keep "Today" open and the rest minimized. # Inspect a recorded request Source: https://kurlo.dev/docs/guides/history/inspect/ ## The entry view Click an entry to open it on its own page — a *History* tab in the title bar, closed like any other tab. It shows what was sent and what came back, side by side: - **Request** — the method and full URL, the header rows the request carried (secret values stay masked), the auth type, and the body. Headers Kurlo adds on the wire, such as `Host` and `User-Agent`, are not part of the entry. - **Response** — status, time, size and content type, then the stored response headers and body in the same viewer as the response panel, with syntax highlighting and line numbers. If the request it was sent from still exists, the page says where it lives, and the link opens it. **Copy as cURL** copies the request as it was sent, **Delete** removes the entry, and **Open in editor** brings it back as a request you can change and send again. ### Open in editor **Open in editor** copies the entry into the collection you are working in as a new request, opens it, and restores the stored response into the response panel — no need to re-send just to look at what you got. Re-sending would answer a different question anyway: the server may not reply the same way it did an hour ago. The new send becomes a fresh history entry. ### Stored responses Kurlo keeps the response of each entry — status, headers and body — in the encrypted profile, up to 2 MB per entry. A larger body is cut to fit and the page says so; a binary body is not kept. A row whose response was kept shows a small dot next to its status code. # Manage history Source: https://kurlo.dev/docs/guides/history/manage/ ## History entry menu The `•••` button on each history row offers: - **Open in editor** — [open the recorded request in a new tab](https://kurlo.dev/docs/guides/history/inspect/#open-in-editor). - **Save as example** — keeps the stored response as an example on the request that is open. Shown when a request is open and the entry's response was kept. - **Save to** a collection — pick an existing collection in this workspace; Kurlo drops the request into it. Useful when an ad-hoc curl-paste turns out to be worth keeping. - **New collection…** — same, but creates the collection on the fly with a name you pick. - **Delete** — removes just this one history record. ## Bulk operations The `•••` button in the History header has: - **Clear all** removes history entries and their stored responses across workspaces in the current profile. Kurlo asks for confirmation and keeps your saved collections. There's no per-day clear in the UI — if you want to keep specific days, save them to a collection first, then *Clear all*. # Retention and privacy Source: https://kurlo.dev/docs/guides/history/retention/ ## Retention By default Kurlo keeps: - **14 days** of history, or - **1 000 entries** total, whichever comes first. When you exceed either cap, the oldest entries are pruned the next time the request store is saved. Pruning happens silently in the background; you don't need to clear history manually unless you want to. These caps aren't exposed in Settings yet — they're constants in the source. If you find yourself wanting longer retention, file a request on GitHub. ## Finding an entry The filter at the top of the History panel matches URLs and request names, and the status buttons narrow the list to `2xx`, `3xx`, `4xx` or `5xx`. The command palette (`Cmd/Ctrl K`) searches saved requests, not history. ## Privacy & data location History entries are stored in encrypted `requests.json` with the rest of the local profile. They never leave your machine unless you explicitly include them in an all-data export. If you delete the data directory (see [Privacy](https://kurlo.dev/privacy/)), history goes with it. When you *Export all data* from Settings, history is included in the JSON export. *Import all data* replaces the entire profile, including history. ## Common questions **Does history persist across restarts?** Yes. The entries live in the encrypted `requests.json`. Response bodies are stored separately in `history/`, one file per entry, and encrypted with the same key. **What about large responses?** A stored response is capped at 2 MB. Past that only the head is kept, and reopening it says so. The status code, headers, duration, and test results are kept in full. **What about binary responses?** History records the status, headers, and size of binary responses. The binary body is excluded. **Are stored responses cleaned up?** Yes. A response file is deleted when its entry falls out of the 14-day window, when you delete the entry, and when you clear history. **Can I disable history?** Recording is automatic. Use **Delete** on a history entry to remove it, or [clear the profile's history](https://kurlo.dev/docs/guides/history/manage/#bulk-operations). # Cookies Source: https://kurlo.dev/docs/guides/cookies/ > Manage your workspace cookie jar, sync cookies from your browser, and control when requests send them. Kurlo keeps a per-workspace cookie jar, similar to a browser. Cookies received from `Set-Cookie` are stored locally and attached to future matching requests unless that request disables the jar. # Sending and receiving cookies Source: https://kurlo.dev/docs/guides/cookies/sending/ ## How cookies are sent For HTTP, GraphQL, SSE, WebSocket, and Socket.IO handshakes, Kurlo checks the cookie jar before sending: - Domain and path must match the request URL. - Secure cookies are only sent over secure schemes. - Expired cookies are ignored. - Host-only cookies stay scoped to their original host. - Manual `Cookie` headers remain visible in the request preview and are not hidden by the jar. gRPC does not use the browser-style cookie jar path. ## Reading cookies from responses When a response includes `Set-Cookie`, Kurlo stores it in the active workspace jar. The jar is encrypted alongside the rest of the request store. Cookies are refreshed after normal sends and after Collection Runner runs. # Manage the cookie jar Source: https://kurlo.dev/docs/guides/cookies/manage/ ## Managing cookies Open cookies from the cookie icon at the bottom of the activity rail, on the far left of the window. Cookies work like environments: the sidebar lists **Browser sync** and every domain in the jar, and the main area shows the domain you pick, with its cookie count, how many last only for this session and how many have expired. Click a request tab to go back to your request. - **Find a domain** with the filter above the list. A yellow dot and *some without a value* under a domain mean one of its cookies has no value on this computer. - **Add a domain** with **+** next to the **Cookies** heading; Kurlo opens a new cookie for it straight away. When the jar is empty, the main area offers to add a cookie for the domain of the open request or any domain you type. - **Read cookies at a glance.** The table shows each cookie's value, path, when it expires and its flags: HttpOnly, Secure, SameSite and Subdomains for cookies sent to subdomains as well. Expired cookies are struck through. - **Cookies from another computer.** A cookie created on another machine keeps its value in that machine's Kurlo profile, and the workspace files only reference it. Kurlo shows such a cookie with an empty value marked *Not on this computer*, in the **Raw** editor too, and does not send it. Type the value and save to use it here; saving without a value keeps the reference. - **Set when a cookie expires** with the **Expires** field: pick a day in the calendar, type the time, or choose **In 1 hour**, **Tomorrow**, **In 7 days** or **In 30 days**. The arrow keys move between days and `Escape` closes the calendar. **Clear** turns the cookie back into a session cookie. - **Edit a cookie** by clicking its row. The editor opens under the table; `Cmd/Ctrl Enter` or **Save** stores the change and `Escape` closes the editor without saving. - **Delete** one cookie with the cross at the end of its row. The **•••** menu next to **Add cookie** deletes every cookie of the domain, clears the whole jar, or reloads the jar from disk. The editor has two modes: - **Fields** — name, value, path, expiry date, SameSite, HttpOnly, Secure and **Include subdomains**. Leave **Expires** empty for a session cookie. - **Raw** — the cookie as `Set-Cookie` text, for pasting from DevTools or a server log: ```text session=abc123; Path=/; Secure; HttpOnly; SameSite=Lax ``` Switching modes carries the cookie across, and both follow the same rules: `SameSite=None` needs **Secure**, and a name cannot contain spaces, `=` or `;`. A `Domain=` attribute in Raw mode moves the cookie to that domain and makes it apply to subdomains. ## Disabling the jar for one request Open the request **Settings** tab and turn off **Use the cookie jar**. Kurlo will not store cookies from that response and will not attach jar cookies to that request. You can still send a manual cookie: ```text Cookie: debug=true; session=manual ``` This is useful when reproducing a production request exactly from a copied cURL command. # Browser cookie sync Source: https://kurlo.dev/docs/guides/cookies/sync/ ## Sync cookies from your browser **Browser sync**, at the top of the cookie sidebar, pairs Kurlo with a browser extension, so a session you already have in Chrome, Edge, Brave or Firefox is the session Kurlo sends with. It is the local answer to copying a `Cookie:` header out of DevTools after every login. Cookies flow one way — browser into Kurlo — and three separate gates stand in front of them: 1. **The bridge has to be on.** The switch at the top of the **Browser sync** page opens a listener bound to `127.0.0.1` (port 3199 by default). Nothing listens until you ask for it. 2. **You have to let the browser in.** The extension finds Kurlo by itself and asks to connect; Kurlo shows the request with a six-digit code and the extension shows the same code. Approve it only if the numbers match — that is what stops anything else on the machine from being approved in its place. 3. **The domain has to be allowlisted twice.** Kurlo only accepts cookies for the domains listed on the page, and the browser only lets the extension read the domains you grant in its popup. A domain missing from either list is never read and never sent. A domain that cannot hold cookies of its own — a public suffix like `com` or `co.uk` — is refused with an explanation rather than accepted and quietly ignored. # Connect a browser Source: https://kurlo.dev/docs/guides/cookies/connect-browser/ ## Connecting a browser 1. Open **Browser sync** in the cookie sidebar and turn on the switch at the top of the page. 2. Under **Browser extension** on the same page, pick **Chrome, Edge, Brave** or **Firefox**. Kurlo puts the extension in a folder and opens it. In Chrome, Edge or Brave, open `chrome://extensions`, turn on **Developer mode**, press **Load unpacked** and pick that folder. In Firefox, open `about:debugging#/runtime/this-firefox`, press **Load Temporary Add-on** and pick `manifest.json` in it. 3. Open the extension and press **Connect**. It scans ports 3199–3203 for Kurlo's bridge. 4. Approve the request in Kurlo once the codes match. Kurlo hands the extension a token; from then on it reconnects on its own and never asks again. 5. Press **Grant domain access** in the extension and accept the browser's prompt, so it may read the allowlisted domains. The extension has the same version as Kurlo. Kurlo keeps the folder up to date when it updates, so the browser loads the new version the next time it starts, or when you press **Reload** on the extension. If a connected extension is older than Kurlo, the page says so. Each release on GitHub also has the extension as a zip, `kurlo-cookie-sync--chromium.zip` and `-firefox.zip`, for setting it up without the app. **Pair manually** in both places is the fallback for when discovery cannot work — a non-default port, say. The code it shows carries the port and the token, so treat it like a password. In Kurlo it sits under **Connection**, hidden until you press **Show code**. # Cookie sync behavior Source: https://kurlo.dev/docs/guides/cookies/sync-behavior/ ## What a sync does to the jar Once connected, the extension holds an open WebSocket to Kurlo, and the two directions of traffic are: - **Live changes.** Every cookie the browser sets, updates or clears for an allowlisted domain is pushed as it happens, so a fresh login shows up in Kurlo within a second. - **Reconciliation.** On connect and every five minutes the extension sends a full snapshot of the allowlisted domains. A snapshot is authoritative: Kurlo replaces everything the jar held for those domains, which is how a cookie you cleared while the browser was closed disappears here too. Domains the snapshot does not cover are left alone. - **Allowlist updates.** Add or remove a domain in Kurlo and the extension is told immediately — no polling, and removing a domain stops it being read at once. A cookie you typed by hand for a synced domain is replaced by the browser's view of it. Cookies land in the jar of the workspace you have open, and follow you when you switch workspaces. The bridge closes when Kurlo quits and reopens on the next start if you left it on; the token is kept, so the browser reconnects on its own. **Disconnect** mints a new token, which drops the browser immediately. Kurlo tells the extension that this is what happened, so it drops its own token and asks to connect again rather than retrying with a key that no longer works. The extension's **Forget** does the same from the other side. ## When it will not sync - **Nothing on the allowlist.** The extension is told there is nothing to read. - **Permission not granted.** The extension reports only the domains it could actually read, so a domain it cannot read is left out of the snapshot instead of looking empty and clearing the jar. Kurlo marks those domains on the page and names them, rather than leaving you to wonder why nothing arrives. - **Kurlo is closed or sync is off.** The extension retries with a backoff and reconnects when the bridge comes back. # Browser emulation and privacy Source: https://kurlo.dev/docs/guides/cookies/privacy/ ## Browser emulation and CORS Browser request emulation can apply Origin, user-agent, CORS, and CSP checks, but it does not move cookies into a browser. Cookies remain in Kurlo's local jar and follow Kurlo's request settings. If **Browser request emulation** and **Use the cookie jar** are both on, the request preview shows which headers come from emulation and which cookie header comes from the jar. ## Backup and privacy Cookies are included in all-data backups and in the encrypted local request store. Collection exports do not include the runtime cookie jar. Cookie sync adds one local surface: a loopback-only HTTP listener, off unless you turn it on, reachable only with the pairing token. The token and the sync allowlist live in `preferences.json` next to the request store, with the token encrypted by the same key as the store; no cookie leaves the machine, and the browser extension talks to `127.0.0.1` and nothing else. If you need to remove sensitive cookies, clear them from the cookie page or clear request history/all data from Settings. # Proxy configuration Source: https://kurlo.dev/docs/guides/proxy/ > Configure Kurlo's global, collection, and request proxy behavior, including system settings, SOCKS5, authentication, and bypass rules. Kurlo can use a global proxy on this device and a proxy URL stored with a collection or request. # Global proxy settings Source: https://kurlo.dev/docs/guides/proxy/global/ ## Precedence Kurlo resolves proxy configuration in this order: 1. A non-empty proxy URL explicitly set on the request. 2. A collection proxy URL inherited by a request that has not overridden that setting. 3. The app-wide proxy under **Settings -> Proxy**. Clearing the proxy field on a request marks that field as a request override. The request then skips the collection proxy and falls back to the app-wide setting. Click **Reset** in the request Settings tab to clear its override markers and inherit collection defaults again. :::note Kurlo does not have a `direct://` per-request value. To connect directly, remove request and collection proxy URLs and set the global mode to **Off**. ::: ## Global modes Open **Settings -> Proxy** and choose: | Mode | Behavior | |------|----------| | **Off** | Connect directly. Environment proxy variables are ignored. | | **On** | Use the custom HTTP, HTTPS, or SOCKS5 proxy configured below. | | **System** | Use the standard `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment behavior. | When **On** is selected, Kurlo requires a hostname. If it is blank, requests fail instead of silently going direct. For a custom proxy, configure: - **Protocol**: HTTP, HTTPS, or SOCKS5. - **Hostname**: without a URL scheme. - **Port**: `0` uses the protocol's normal URL behavior; SOCKS5 defaults to `1080`. - **Auth**: optional username and password. - **Proxy Bypass**: hosts that must connect directly. The global proxy password is kept only in the running app. Kurlo deliberately removes it from persisted preferences and all-data backups, so you must enter it again after restarting Kurlo or restoring a backup. # Bypass rules Source: https://kurlo.dev/docs/guides/proxy/bypass/ Separate bypass entries with commas, semicolons, spaces, or new lines: ```text localhost, 127.0.0.1, .internal, *.example.test ``` Matching is case-insensitive: - `example.test` matches that host and its subdomains. - `.example.test` and `*.example.test` use the same suffix behavior. - `*` bypasses the proxy for every host. Enter hostnames only, without a scheme or port. # Collection and request proxies Source: https://kurlo.dev/docs/guides/proxy/request-proxy/ ## Collection and request URLs The collection and request fields accept a complete proxy URL: ```text http://proxy.example.com:8080 https://proxy.example.com:8443 socks5://127.0.0.1:1080 http://username:password@proxy.example.com:8080 ``` A request URL is the strongest override. A collection URL applies to requests that still inherit that setting. When the effective URL is empty, Kurlo uses the global mode. Credentials embedded in a request or collection proxy URL become part of that saved API data. Do not put them in a shareable workspace; use the device-local global proxy authentication fields instead. Kurlo does not expand `{{variables}}` inside proxy URLs. ## Troubleshooting If every request fails after enabling a custom proxy: 1. Confirm the global hostname is not blank. 2. Verify protocol and port with another client. 3. Re-enter the password after an app restart. 4. Clear request and collection proxy fields while testing the global setting. 5. Check whether a bypass entry is sending the target direct. TLS verification still applies to the final HTTPS connection. If a corporate proxy intercepts TLS, install its root CA into the operating-system trust store instead of disabling verification broadly. # Browser security emulation Source: https://kurlo.dev/docs/guides/browser-security/ > Reproduce browser-like Origin headers, credentials mode, CORS preflights, and CSP connect-src blocking. Kurlo normally behaves like an API client, so it is not restricted by browser CORS or CSP rules. Browser security settings let you reproduce the result that frontend code would see without moving the request into a browser. Configure them in a request's **Settings** tab or as [collection defaults](https://kurlo.dev/docs/guides/collection-defaults/). # Browser origin and credentials Source: https://kurlo.dev/docs/guides/browser-security/configure/ ## Browser origin Enter the page origin that would initiate the request: ```text http://localhost:5173 https://app.example.com ``` Kurlo accepts `http://`, `https://`, or the special CORS origin `null`. It normalizes host casing and removes default ports. CORS and CSP checks require an origin even if **Browser request emulation** itself is off. For CSP checks, use an HTTP or HTTPS origin; `null` cannot act as the protected page origin. ## Request emulation **Browser request emulation** sends a browser-like `User-Agent`, the configured `Origin`, and fetch metadata: - HTTP and SSE requests receive `Sec-Fetch-Dest`, `Sec-Fetch-Mode`, and `Sec-Fetch-Site`. - WebSocket and Socket.IO handshakes send `Origin` but do not add fetch metadata headers. - Same-origin and cross-origin status is calculated from scheme, hostname, and effective port. Enabling CORS or CSP checks also activates the browser-like user agent and origin handling. ## Credentials mode **Include browser credentials** controls cross-origin cookie behavior and CORS validation: - Off: Kurlo suppresses cookie-jar cookies on an active cross-origin browser-security request. - On: cookies may be sent according to the normal cookie-jar rules, and CORS requires `Access-Control-Allow-Credentials: true`. With credentials enabled, `Access-Control-Allow-Origin: *` is rejected; the server must return the exact emulated origin. This option does not enable the cookie jar by itself. The request's **Disable cookie jar** setting still wins. # Enforce CORS Source: https://kurlo.dev/docs/guides/browser-security/cors/ For cross-origin HTTP requests, **Enforce CORS** validates the response as a browser would. For standard HTTP requests, Kurlo sends an `OPTIONS` preflight when the method or request headers are not CORS-safelisted. Safelisting looks at the value as well as the name, as the Fetch standard does: - `Accept`, `Accept-Language`, `Content-Language`, `Content-Type` and `Range` are the only safelisted names, and each value must be 128 bytes or shorter. - No value may contain `"`, `(`, `)`, `:`, `<`, `>`, `?`, `@`, `[`, `\`, `]`, `{`, `}` or a control character. - `Accept-Language` and `Content-Language` allow only letters, digits, space and `*,-.;=`. - `Content-Type` must be `application/x-www-form-urlencoded`, `multipart/form-data` or `text/plain`. - `Range` must be a single `bytes=N-` or `bytes=N-M`; a suffix range such as `bytes=-500` needs a preflight. - When the safelisted values add up to more than 1 KB, all of them need a preflight. The timeline shows separate preflight start and finish events. Request timings exclude the preflight. The preflight: - Does not include cookie-jar cookies. - Does not follow redirects. - Validates the 2xx status, allowed origin, method, headers, and credential rules. - Honors `Access-Control-Max-Age`, capped at five minutes. The actual response must also pass the origin and credential checks. Same-origin requests skip CORS enforcement. ## Redirects Kurlo follows redirects the way a browser does in `cors` mode, checking every hop: - A redirect response from a cross-origin server must pass the same origin and credential checks before Kurlo follows it. - A request that starts same-origin becomes a CORS request as soon as a redirect leaves the page's origin, and stays one for the rest of the chain. - A non-simple request is preflighted again at each new cross-origin target. - When the chain moves from one cross origin to another, the `Origin` header becomes `null`, and the target must allow `null` or `*`. - `Authorization` is removed whenever the origin changes, whatever the redirect settings say. - Without **Include browser credentials**, cookies stop being sent and stored once the chain has left the page's origin. - A `Location` with a username or password in it is refused. - `Sec-Fetch-Site` stays `cross-site` once any URL in the chain was cross-origin. - A `301` or `302` turns only `POST` into `GET`; a `303` turns everything but `GET` and `HEAD` into `GET` and drops `Content-Type` with the body. ## Headers hidden from page code A browser hands page script only part of a cross-origin response: `Cache-Control`, `Content-Language`, `Content-Length`, `Content-Type`, `Expires`, `Last-Modified`, `Pragma`, and the headers the server lists in `Access-Control-Expose-Headers`. `Access-Control-Expose-Headers: *` exposes the rest, but not for a credentialed request, where `*` is just a header name. `Set-Cookie` is never exposed. With **Enforce CORS** on, the response's Headers tab marks every other header *hidden from page*. They are still shown, and test scripts still see them, so a script can assert on `Access-Control-Allow-Origin`; the mark is there to explain why `response.headers.get("X-Total-Count")` returns `null` in the browser. SSE validates the actual cross-origin response and follows the redirect rules above but does not run the separate preflight path. WebSocket and Socket.IO settings expose origin/CSP emulation but not browser CORS enforcement; browsers apply their handshake-origin rules instead of Fetch CORS preflights. Common failures include: - Missing or duplicate `Access-Control-Allow-Origin`. - A different allowed origin than the one configured in Kurlo. - Wildcard origin on a credentialed request. - Missing method or header permission in the preflight response. - `Authorization` covered only by a wildcard header rule; it must be named explicitly. # Enforce CSP connect-src Source: https://kurlo.dev/docs/guides/browser-security/csp/ Paste the page's `Content-Security-Policy` value and enable **Enforce CSP connect-src**. Kurlo checks the target before opening the network connection and checks redirect targets as they are followed. Kurlo uses `connect-src` when present and otherwise falls back to `default-src`. If neither directive exists, this check does not block the request. Supported source matching includes: - `'self'` and `'none'` - `*` - Explicit schemes such as `https:` - Hosts, ports, and wildcard subdomains - HTTP-to-HTTPS and WS-to-WSS upgrades allowed by the implemented source rules This is focused `connect-src` emulation, not a complete browser CSP engine. Directives unrelated to network connections are ignored. # Mixed content and local networks Source: https://kurlo.dev/docs/guides/browser-security/mixed-content/ ## Mixed content A page served over HTTPS may not fetch `http://` URLs or open `ws://` sockets. The exceptions are targets a browser already trusts — `localhost`, `*.localhost`, `127.0.0.0/8` and `[::1]` — and, under Local Network Access, private IP literals such as `192.168.1.20` and `.local` names. When **Enforce CORS** or **Enforce CSP connect-src** is on, Kurlo blocks a mixed-content request before it opens a connection, and checks redirect targets the same way. With only **Browser request emulation** on, it sends the request and adds a warning. ## Local Network Access Chrome treats a request from a page to an address that is *less public* than the page's own as a local network request. The address spaces, from most to least public, are public, local network (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `100.64.0.0/10`, `169.254.0.0/16`, `fc00::/7`, `fe80::/10`, and `.local` names) and loopback (`127.0.0.0/8`, `::1`, `localhost`). Kurlo classifies the target by the address it actually connected to, so a public name that resolves to a private address counts. Through a proxy only the URL itself can be judged. The page's space comes from the origin you entered: an IP literal, `localhost` or `.local`, and public otherwise. For such a request Kurlo adds a warning to the response instead of blocking it, because the outcome depends on the person using the page: - From an HTTPS page, Chrome first asks the user for permission to reach devices on the local network, and the request fails if they decline. - From an HTTP page on a public or local origin, Chrome refuses the request: local network access is only available to secure contexts. A page on `localhost` may reach any address. WebSocket and Socket.IO handshakes are not checked, because Chrome does not gate them yet. The older Private Network Access preflight (`Access-Control-Request-Private-Network`) is not sent; Chrome replaced it with the permission prompt. ## Recommended workflow 1. Send the request with browser security disabled to verify basic connectivity. 2. Enter the frontend page origin and enable request emulation. 3. Enable CORS and fix server response headers until the request passes. 4. Paste the deployed page policy and enable CSP. 5. Turn on credentials only if frontend code intentionally sends cookies across origins. ## In CI and for AI assistants [`kurlo run`](https://kurlo.dev/docs/guides/cli-runner/) and [`kurlo mcp`](https://kurlo.dev/docs/guides/mcp-server/) honor the same settings, saved on a request or inherited from its collection. A run fails on a request the browser would refuse, so a CORS change breaks the build before it breaks the frontend. An assistant can also check any call against an origin with the `browserOrigin` argument of `run_request` and `send_request`. For cookie storage and domain matching, see [Cookies](https://kurlo.dev/docs/guides/cookies/). # Workspaces & collections Source: https://kurlo.dev/docs/guides/workspaces/ > How Kurlo organizes your requests — workspaces, collections, folders, drag-and-drop, and starred favourites. Kurlo arranges your requests in a workspace -> collection -> folder tree: ``` Workspace └─ Collection ├─ Folder │ ├─ Subfolder │ │ └─ Request │ └─ Request └─ Request ``` Use **workspaces** to separate unrelated work (personal · day-job · client X), **collections** to group requests by API or domain (`Stripe v2024` · `internal billing`), and **folders/subfolders** to slice a large collection by feature, version, or test scenario. # Manage workspaces Source: https://kurlo.dev/docs/guides/workspaces/workspaces/ ## Workspaces A workspace groups its collections, environments, and cookie jar. [Request history](https://kurlo.dev/docs/guides/history/) is stored across workspaces in the current profile. ### Creating a workspace Open the **Workspace switcher** and click **Create**, or click **New workspace** on the workspace overview. To rename a workspace, click its name at the top of the overview. **Enter** saves the new name and **Esc** cancels. On macOS the workspace name sits above the sidebar, at its right edge. When you hide the sidebar it moves to the start of the top bar. ### Switching workspaces The same dropdown shows all workspaces with their request counts. Switching is instant — Kurlo keeps each workspace's open tabs, active environment, and last-viewed request restored separately. ### Workspace overview If no request is open, the workspace overview is shown. Under the workspace name — with how many collections, requests and environments it holds, and whether it lives in a Git repository — it lists: - **Continue where you left off** — the last requests you sent from this workspace, newest first, with the status each one got. Click one to open it. Point at an HTTP, GraphQL or gRPC request to get a **Send** button that opens it and sends it again in one click. Requests you have since deleted are left out. - **Collections** — every collection with its request and folder count. Click one to open its settings. - **Start** — tiles for new request, search, import, run a collection, new collection and new environment, with the shortcut shown where there is one, and a link to the keyboard shortcuts. - **README** — Markdown notes for whoever opens the workspace next: base URLs, auth hints, which environment is safe to break, links. It shows rendered; **Edit** switches to the text and **Done** or **Esc** back. With manual save, the README stays unsaved until you click **Save**; the round arrow (**Revert**) next to it throws the edits away, and **Done** leaves the editor without saving. Kurlo keeps it as `README.md` in the workspace folder, so a Git host shows it when you browse that folder, and changes made to that file outside Kurlo show up here. A long README is folded to its first screen with **Show all** under it. A `README.md` that is over 256 KB, is not UTF-8 text, or is a link to another file shows as read-only with the reason, and Kurlo never changes or deletes it. A workspace with nothing in it yet shows a short first-run panel instead: start a new request (paste a URL or a whole cURL command) or import a collection from Postman, Insomnia, OpenAPI, Bruno / OpenCollection or HAR. # Manage collections Source: https://kurlo.dev/docs/guides/workspaces/collections/ ## Collections A collection groups related requests inside a workspace. There's no maximum — you can have hundreds of small collections or a few large ones. ### Creating a collection - Sidebar header → **+** (the plus button) - Workspace overview → *Start* → **New collection** - Right-click anywhere in the empty sidebar area → *New collection* - Empty-state CTA when a workspace has no collections yet Each collection has a **name**, a **filesystem name** (auto-derived for Git sync), and child folders/requests. Inline rename: double-click the collection title in the sidebar. ### Collection menu The `⋯` button next to a collection reveals: - **Add request** / **Add folder** — quick creators that drop new items into this collection - **Settings** — opens the collection overview and its defaults. Click **Run** at the top of that page to open the [Collection Runner](https://kurlo.dev/docs/guides/collection-runner/) for this collection. - **Rename** — opens the same inline editor as double-click. - **Export…** — opens the format picker for [collection exports](https://kurlo.dev/docs/guides/import-export/export/#export), including files and folders. - **Show in Finder** / **Show in Explorer** — shows the collection's folder in the workspace on disk, so you can see its YAML files or open them in another editor. On Linux it is **Show in file manager**. - **Delete collection** — asks for confirmation before removing the collection and its contents. You can restore it from **Recently deleted** until you quit Kurlo. ### Drag-and-drop reorder Hover the `⋮⋮` handle on the left of a collection row to grab it. Drag onto another collection — drop above (top half) or below (bottom half) to set the new position. Order persists between sessions. Drag-and-drop is disabled while a search is active in the sidebar (the order you see is sorted by relevance, not user order). # Folders and defaults Source: https://kurlo.dev/docs/guides/workspaces/folders/ ## Folders Folders are optional. They're useful when a single collection has too many requests to scan quickly. ### Creating a folder - Collection `⋯` menu → **Add folder** - Inside a folder, the folder's `⋯` menu → **Add subfolder** Folders can nest up to **4 levels deep** (a cap to keep the tree usable). Empty folders are preserved, so creating a folder does not force you to create a request immediately. Once a folder contains **50 requests**, **Add request** is disabled in its menu. ## Collection defaults Open a collection workspace to configure reusable headers, variables, auth, scripts, tests, and transport settings. Requests can override headers and settings per field; auth is inherited only when the request uses **Inherit auth**. Active environment values override collection variables with the same key. To set headers, authentication, a pre-request script, or tests for a folder and its subfolders, open the folder's **⋯** menu and choose **Settings**. See [Folder defaults](https://kurlo.dev/docs/guides/collection-defaults/folders/) for inheritance and storage. ### Folder menu The `⋯` next to a folder offers: - **Add request** — drops a new request inside this folder - **Add subfolder** — creates a child folder - **Run folder** — Collection Runner scoped to just this folder's requests - **Settings** — edit the folder's defaults - **Rename** — inline rename - **Delete folder** — asks for confirmation before removing the folder and its contents. # Manage saved requests Source: https://kurlo.dev/docs/guides/workspaces/requests/ ## Requests A request is the leaf of the tree. Each request has its own URL, method, headers, body, auth config, pre-request and test scripts, settings, and notes. ### Creating a request - Collection or folder `⋯` menu → **Add request** - Workspace overview → *Start* → **New request** - Drafts: **+** after the open tabs opens an unsaved HTTP request. Use the method and protocol picker at the start of the URL bar to switch request types before saving. With manual saving, a request added from a collection or folder starts as a draft too, marked with a dot on its tab. It already uses the headers, auth, scripts and variables of that collection and folder, and **Save** puts it there without asking where. With autosave on, it is saved straight away. Closing a draft asks whether to save it only when you have changed it since it opened. An untouched draft, like an empty tab from **+**, closes without asking. ### Docs The **Docs** tab of a request is written in Markdown: headings, **bold**, `code`, lists, task lists, tables, quotes, links and images. **Edit** shows the text on the left and a live preview on the right; **Preview** shows the rendered page, followed by a reference Kurlo builds from the request itself: the method and URL, the auth type, and the enabled path variables, query params, headers and body, with the description you gave each row. Links open in your browser, and secret values are masked. A request without docs opens in **Edit**; `Esc` goes back to the preview. ### The request `⋯` menu Right-click (or click the `⋯` button on hover) on any request to reveal: - **Rename** — inline rename; double-click the title also works - **Duplicate** — clones the request, including auth/headers/body/scripts - **Star** / **Unstar** — adds the request to the *Starred* group at the top of the sidebar, or removes it. - **Copy as cURL** — copies a `curl` command for a supported request. Review the command before sharing it. - **Show in Finder** / **Show in Explorer** — opens the folder that holds the request's YAML file with the file selected. On Linux it is **Show in file manager**: file managers that support it, such as Files (Nautilus), Dolphin, Thunar, Nemo and Caja, select the file too, and others open its folder. Unsaved drafts have no file yet, so they do not offer it. - **Delete** — asks for confirmation before removing the request. You can restore it from **Recently deleted** until you quit Kurlo. ### Reordering requests Hover a request to reveal its `⋮⋮` handle on the left. Drag it onto another request in the same collection or folder: the top half places it above, and the bottom half places it below. A line shows the insertion point. The order is saved in `collection.yml` and persists between sessions. To move a saved request, drop it onto a folder header or an empty folder in the same collection. Nested and collapsed folders accept drops too. Drop onto the collection header to move it back to the root. Empty source folders are kept. Clear the sidebar search before dragging. Dragging onto another request changes the order among siblings; dragging onto a folder changes the parent. # Starred and deleted items Source: https://kurlo.dev/docs/guides/workspaces/starred/ ## Starred (favourites) Use **Star** to mark requests you reach for often. Starred requests appear in their own group at the top of the sidebar, **above all collections**, regardless of which collection they live in. Unstar from the same menu to remove them from the favourites group (the request itself stays in its collection). The Starred group only appears when at least one request is starred. It shows up to ten requests and scrolls within that space, so the collections below stay in view however many requests you star. Click the *Starred* header to collapse the group; Kurlo remembers that across restarts. Stars are personal. They are kept in your local workspace data, not in the request files, so they are not committed to Git and teammates do not see them. Stars saved in request files by Kurlo 3.0.4 and earlier are picked up the first time you open the workspace, and the old `isPinned` field is removed from each file the next time it is saved. ## Restoring deleted items Deleting a request, folder, collection or environment shows a message with **Undo** for a few seconds. Undo puts it back where it was, with the same requests, folders, folder defaults, order and AI request chats; a restored environment gets back its child environments and the collections it was pinned to. After the message is gone, the trash button appears in the **Collections** header (requests, folders and collections) or the **Environments** header (environments). It lists the last 20 deletions of the current workspace, newest first; click one to restore it, or choose **Clear list** to forget them. A request or folder whose collection was deleted too can be restored once the collection is back. The list lives only while Kurlo is open: after you quit, deleted items are gone from Kurlo. In a [Git workspace](https://kurlo.dev/docs/guides/git-workspaces/) you can still get the files back from Git until you commit the deletion. Deleting a workspace is not covered. # Search and bulk editing Source: https://kurlo.dev/docs/guides/workspaces/search/ ## Search The sidebar search input filters requests by name, URL, and method as you type: - Plain text matches request names and URLs - Prefixing with `m:` filters by method (`m:POST users`) - Filter is workspace-scoped — searching doesn't leak between workspaces ## Find and replace **Find and replace…** in the menu of a collection or a folder searches every request inside it; the command palette offers it for the collection of the open request. It looks in the URL, query params, path variables, headers, form fields, the body (the query and variables of a GraphQL request), scripts, docs, and the auth fields that hold no secret, such as a token URL or a client ID. - **Aa** matches case, **ab** matches whole words, and **.\*** takes a regular expression, whose groups the replacement can use as `$1` or `$`. - Each match shows the request, the field and the line, with the replacement previewed in place. **Replace** changes one match, **Replace in request** one request, and **Replace all** every match. - **Undo** puts back what the last replace changed, unless a request was edited again since. Secret values are never searched or rewritten: secret rows, tokens, passwords, client secrets and private keys stay as they are. With autosave off, a request with unsaved edits is skipped until you save it, so the replace cannot overwrite your edits. # Command palette Source: https://kurlo.dev/docs/guides/workspaces/command-palette/ Press `Cmd/Ctrl K` — or click **Search** at the bottom right of the window — to open the command palette. Type to find saved requests or Agent chats in the current workspace. Request search matches names, URLs, methods, collections, and folders. The same query filters Kurlo's commands. - **Request** — send, save, edit the URL, duplicate, rename, copy as cURL, close or reopen a tab. Shown while a request is open. - **Create** — a new request, collection or environment, or an import. - **Go to** — collections, environments, history, globals, the collection runner, the mock server, Git, cookies, settings and proxy settings. - **View** — show or hide the sidebar and the code snippet panel, put the response beside or below the request, switch between light, dark and system theme. - **Help** — what's new, reporting an issue, about Kurlo. The response layout also has a button in the status bar, next to the sidebar toggle. Kurlo puts the response beside the request on its own when the editor is at least 1000 px wide; once you choose the side-by-side layout yourself, it keeps it down to 760 px. Dragging the divider stops before either side gets too narrow to use. **Kurlo documentation** sits at the top of the empty palette and opens the docs in your browser. Once you type, the last row becomes **Search Kurlo docs for “…”** and opens the docs with that search already run, so `Enter` still picks the best request or command. Start the query with `>` to list commands only; the docs row is hidden then. `↑` and `↓` move through the list, `Enter` runs the selection, `Esc` closes the palette. A command bound to a shortcut shows it, including one you reassigned in *Settings → Shortcuts*. ## Empty states When something is empty, Kurlo shows a hint so you're never staring at blank space: - **No collections yet** — sidebar onboarding with *New collection* / *Import collection* buttons - **Empty collection** — inline *+ Add request* / *+ Add folder* rows inside the collection - **Empty folder** — same pattern, nested one level deeper Once an item is added, the hint disappears. ## Git storage If the workspace is backed by a folder or Git repository, collections and folders are written to YAML files with explicit `folderPaths`, so empty folders survive round-trips through Git and OpenCollection export. See [Git-backed workspaces](https://kurlo.dev/docs/guides/git-workspaces/) for the full workflow. # Collection defaults Source: https://kurlo.dev/docs/guides/collection-defaults/ > Share headers, auth, scripts, and tests across collections and folders. Set variables and transport defaults at collection level. Collection defaults reduce repeated configuration while preserving request-level control. Open a collection's `...` menu, choose **Settings**, and edit the tabs in the collection workspace. Defaults are applied when a request is sent. Folders can add their own headers, auth, scripts, and tests on top of the collection; see [Folder defaults](https://kurlo.dev/docs/guides/collection-defaults/folders/). # Configure collection defaults Source: https://kurlo.dev/docs/guides/collection-defaults/configure/ ## Available defaults | Tab | What it defines | |-----|-----------------| | Overview | Documentation, pinned environments, and a summary of every default below. | | Headers | Header rows merged into child requests. | | Vars | Collection variables, including values marked secret. | | Auth | Default authentication scheme and credentials. See [Authentication](https://kurlo.dev/docs/guides/authentication/) for supported schemes. | | Script | Collection pre-request script for the selected JavaScript or Tengo engine. | | Tests | Collection test script for the selected engine. | | Proxy | Transport defaults such as HTTP version, TLS verification, client certificates, redirects, and proxy URL. | Use the app-wide script-engine setting to switch between the independently stored JavaScript and Tengo fields. ## Overview The **Overview** tab shows what the collection applies to its requests at a glance: - **Applied to every request** lists Headers, Variables, Auth, Pre-request script, Tests, and Proxy and settings with what each one sets (for example *2 headers*, *Bearer token*, *12 lines* or *None*). Click a row to open its tab. - **Documentation** shows the collection notes as rendered Markdown; **Edit** switches to the text, and **Done** or **Esc** back. Long documentation is folded under **Show all**; documentation over 256 KB is saved but not previewed. - **Environments** pins the environments the switcher lists while you work in the collection and picks the default one. Click the collection name at the top to rename it in place (**Enter** saves, **Esc** cancels). **Run** opens the collection runner and **New request** adds a request to the collection. The **•••** menu holds **Export…**, **Reset defaults**, and **Delete collection**. # Precedence Source: https://kurlo.dev/docs/guides/collection-defaults/precedence/ ## Headers Collection headers are added unless the request contains a row with the same key. Matching is case-insensitive. A request row therefore overrides, or can intentionally suppress, the collection row. Folder headers sit in between: a folder row overrides the collection and the folders above it, and a request row overrides them all. ## Variables Collection variables are available as `{{name}}`. Active environment values override collection values with the same key: ```text active environment > collection variable ``` Values marked **Secret** are masked in the UI and participate in Kurlo's local secret handling for Git-backed workspaces. ## Authentication A request uses inherited auth only when its Auth type is **Inherit auth**. It then takes the auth of the nearest enclosing folder that sets one, or the collection's when no folder does. Selecting **No auth** or another explicit request auth type overrides both. See [Authentication](https://kurlo.dev/docs/guides/authentication/) for each supported scheme. ## Scripts and tests Kurlo combines scripts in a defined order: 1. Collection pre-request script. 2. Folder pre-request scripts, outermost folder first. 3. Request pre-request script. 4. The network request. 5. Request test script. 6. Folder test scripts, innermost folder first. 7. Collection test script. JavaScript and Tengo defaults are kept separately and combined only with request scripts from the active engine. The combined script shares one scope. A top-level `const`, `let` or `class` with the same name at two levels is a redeclaration error that fails the whole request; give each level its own names, or use `var` for a helper you want to share. Postman combines its scripts the same way. ## Transport settings Transport settings inherit per field. Editing a field in the request Settings tab marks only that field as overridden. Other fields can continue to inherit from the collection. The request editor shows the applied collection defaults and labels individual values as inherited or overridden. Clicking **Reset** in the request Settings tab clears all request setting override markers, allowing collection values to apply again when the request is sent. For proxy precedence beyond the collection, see [Proxy configuration](https://kurlo.dev/docs/guides/proxy/). # Folder defaults Source: https://kurlo.dev/docs/guides/collection-defaults/folders/ Open a folder's `...` menu and choose **Settings**. The folder gets the same **Headers**, **Auth**, **Script**, and **Tests** tabs as the collection, and they apply to every request in the folder, subfolders included. - **Headers** are layered collection → outer folder → inner folder → request, and the nearest one with the same key wins. - **Auth** starts as **Inherit from parent**, which passes on whatever the parent folder or the collection sets. Choose a scheme to give the folder's requests their own credentials, or **No auth** to send them without auth even when the collection has a token. - **Script** and **Tests** run in the order listed under [Scripts and tests](https://kurlo.dev/docs/guides/collection-defaults/precedence/#scripts-and-tests). Variables and transport settings stay at the collection level. Renaming a folder keeps its settings; deleting it removes them along with its requests. A refreshed OAuth 2.0 token for an inherited auth is saved to the folder or collection that supplies it. Requests in the folder show what they inherit in their Settings tab. The CLI, the collection runner, load tests, and `kurlo mcp` apply folder defaults the same way the app does. ## Saving and resetting In autosave mode, collection edits are saved after a short delay. In manual-save mode, click **Save**. **Reset defaults**, in the **•••** menu, clears collection headers, variables, auth, scripts, tests, and transport settings after confirmation. It does not delete requests or folders, and folder defaults stay. On a folder's settings, the same menu item clears only that folder's headers, auth, scripts, and tests. ## Storage and export Collection defaults are saved with the collection: - Local profile data is inside encrypted `requests.json`. - Folder and Git workspaces store shareable defaults in YAML. - Folder defaults are saved in `collection.yml` under `folderDefaults`. - Kurlo/OpenCollection export preserves supported collection and folder defaults. Real secret values remain in Kurlo's encrypted local profile when shared YAML uses `{{kurloSecret:...}}` placeholders. See [Kurlo YAML format](https://kurlo.dev/docs/reference/kurlo-yaml-format/) for the storage contract. # Environments & variables Source: https://kurlo.dev/docs/guides/environments/ > Switch between environments, compare values in Matrix, and manage variable scopes and inheritance. Variables in Kurlo use the `{{name}}` template syntax. They expand in URLs, headers, query params, request bodies, and auth fields just before send. Edit the environment name directly in the editor, or double-click its name in the sidebar. `F2` or **Rename** in the editor’s **•••** menu focuses the name field. Press `Enter` or click elsewhere to apply the name; `Escape` cancels the edit. With [manual save](https://kurlo.dev/docs/guides/environments/global/#manual-save-vs-autosave), the new name is saved with the environment's other edits. A name can be up to 100 characters; a long one is shortened with **…** in the sidebar, the environment picker and the Matrix. # Variable scopes Source: https://kurlo.dev/docs/guides/environments/scopes/ ## Scopes A name is looked up in five scopes; when the same name exists in several, the later one in this list wins: 1. **Globals** — **Environments → Globals**, plus values scripts write with `pm.globals.set(...)` or `pm.variables.set(...)`. 2. **Collection variables** — defaults saved with the collection. 3. **Active environment variables** — the selected environment for the workspace. 4. **Request variables** — the request's [**Vars**](https://kurlo.dev/docs/guides/environments/request-variables/) tab. 5. **Data row** — the current row of a data file in the [Collection Runner](https://kurlo.dev/docs/guides/collection-runner/) or [`kurlo run --data`](https://kurlo.dev/docs/guides/cli-runner/data/#data-driven-runs). If nothing matches, the literal `{{name}}` is left untouched so the unresolved template is visible. A name may contain any character except `{` and `}` — letters from any alphabet, spaces and colons included — and spaces around it are ignored, so `{{токен}}`, `{{api key}}` and `{{ token }}` all work. ### Values written by a pre-request script A pre-request script runs before the templates are filled in for good. When it stores a value — `pm.environment.set("token", ...)`, `pm.collectionVariables.set(...)`, `pm.globals.set(...)` — every `{{token}}` in the same request already uses the new value. The script itself still sees the request as it was resolved before it ran, and edits it makes through `pm.request` are kept. ### Variables built from other variables A value may itself contain `{{...}}`, and Kurlo keeps resolving until nothing changes: ``` scheme = https host = api.example.com baseUrl = {{scheme}}://{{host}} ``` A request pointed at `{{baseUrl}}/users` goes to `https://api.example.com/users`. This is the usual way to keep one place to edit when a whole collection moves to staging. Resolution stops after 20 rounds. A chain that refers back to itself — `a = {{b}}`, `b = {{a}}` — keeps its braces rather than looping, so the send fails with an unresolved-variable message pointing at the real culprit. # Request variables Source: https://kurlo.dev/docs/guides/environments/request-variables/ The **Vars** tab of a request holds variables that belong to that request only. It has two tables, as in Bruno. **Pre Request** variables are set before the request is sent. They win over environment, collection and global values with the same name, so a request can pin `userId` or `page` without touching the shared environment. A value may use other variables: `{{tenant}}-eu` takes `tenant` from the environment, and a variable named after an environment value, such as `region = {{region}}-backup`, extends that value instead of referring to itself. Rows lower in the table can use the rows above them. Scripts read them with `pm.variables.get(...)` and `pm.variables.replaceIn(...)`. **Post Response** variables are filled from the response once it arrives, before the post-response script and the tests run. The value column holds a JavaScript expression with `res` in scope: | Expression | Value | |---|---| | `res.body.token` | A field of the JSON body. The body is the text when it is not JSON. | | `res('data.items[0].id')` | The same with a path string. | | `res.status`, `res.statusText` | The status code and text. | | `res.getHeader('x-request-id')` | A header; `res.headers` has all of them with lowercase names. | | `res.responseTime` | The time in milliseconds. | The result is stored like `pm.variables.set(...)`: a global that later requests and runs can use with `{{token}}`. Strings are stored as they are and other values as JSON. An expression that fails or returns `undefined` leaves the variable unchanged and writes a line to the console. Post Response variables run for HTTP and GraphQL requests, in the app, the [Collection Runner](https://kurlo.dev/docs/guides/collection-runner/), [`kurlo run`](https://kurlo.dev/docs/guides/cli-runner/) and [`kurlo mcp`](https://kurlo.dev/docs/guides/mcp-server/). Other request types show only the Pre Request table. Both tables are saved in the request's YAML file as `vars` and `postResponseVars`. # Dynamic variables Source: https://kurlo.dev/docs/guides/environments/dynamic-variables/ Names beginning with `$` are generated at send time and need no environment entry. They match Postman's names, so imported collections that use them keep working. ``` GET https://api.example.com/orders?trace={{$guid}}&ts={{$timestamp}} ``` Every occurrence is generated independently — two `{{$guid}}` in one request produce two different ids. An environment variable with the same name wins, so you can pin one when a test needs a fixed value. | Group | Names | |-------|-------| | Identity & time | `$guid`, `$randomUUID`, `$timestamp`, `$isoTimestamp`, `$randomDatePast`, `$randomDateFuture`, `$randomDateRecent` | | Numbers & text | `$randomInt`, `$randomBoolean`, `$randomAlphaNumeric`, `$randomWord`, `$randomWords`, `$randomLoremSentence`, `$randomLoremParagraph`, `$randomPassword`, `$randomSemver` | | People | `$randomFirstName`, `$randomLastName`, `$randomFullName`, `$randomUserName`, `$randomEmail`, `$randomExampleEmail`, `$randomPhoneNumber`, `$randomJobTitle` | | Network | `$randomIP`, `$randomIPV6`, `$randomMACAddress`, `$randomDomainName`, `$randomDomainWord`, `$randomUrl`, `$randomProtocol`, `$randomPort`, `$randomUserAgent` | | Places | `$randomCity`, `$randomCountry`, `$randomCountryCode`, `$randomStreetAddress`, `$randomLatitude`, `$randomLongitude` | | Business | `$randomCompanyName`, `$randomBankAccount`, `$randomCreditCardMask`, `$randomPrice`, `$randomCurrencyCode`, `$randomCurrencyName`, `$randomCurrencySymbol` | | Files & colour | `$randomMimeType`, `$randomFileName`, `$randomFileExt`, `$randomColor`, `$randomHexColor` | `$isoTimestamp` is the current UTC time with milliseconds, such as `2026-11-17T09:30:00.123Z`, the same in the app, `kurlo run` and `kurlo mcp`. The editor's `{{` autocomplete lists them alongside your own variables. A `{{$name}}` Kurlo doesn't implement is left as-is rather than sent as an empty value. # Manage and switch environments Source: https://kurlo.dev/docs/guides/environments/manage/ ## Comparing environments An environment opens on its own page with only its variables. With two or more environments, the page also has a **Matrix** view: every variable of the workspace as a row, environments as columns, the one in use highlighted. It answers "what is `baseUrl` in staging?" and "which environment is missing a token?" without opening each environment. - Type in a cell to change that environment's value. A cell that says *Not set* has no such variable in that environment; click it to set one. - Rename a variable in its row and it is renamed in every environment. - The lock marks a variable secret everywhere — masking it in one environment and showing it in another would leak it anyway. The eye shows the values while you look. - **+ Variable** adds a variable to every environment at once, empty; the bin removes it from all of them. - **×** in a cell removes the value from that environment only, and the cell goes back to *Not set* or to the inherited value. It shows only while another environment still sets the variable — to delete the last one, use the bin. - The Matrix shows the environment in use and up to four more. **Environments** above the table picks which ones to compare, with a search for long lists; **Show all** adds every environment and **Reset** goes back to the first five. Kurlo remembers the choice for each workspace. - The variable names stay on the left while you scroll across the columns. - Click an environment's name to open it on its own. **Single** switches back to one environment at a time; Kurlo remembers which view you used. ## Inheriting from another environment Environments often share most of their variables and differ in a few: staging and production use the same paths and client ID but different hosts and tokens. Instead of copying the shared ones into each, keep them in one environment, say *Base*, and let the others inherit from it. Open an environment and pick its parent under **Inherits from**. A variable the environment does not set itself is taken from its parent, and from the parent's parent after that; the nearest one that sets it wins. Requests, the collection runner, load tests, the CLI and [`kurlo mcp`](https://kurlo.dev/docs/guides/mcp-server/) all resolve variables this way. - The **Inherited** list under the variables shows what comes from the parent and from where. **Override** copies a value into this environment so you can change it there. - In the **Matrix**, a cell the environment does not set shows the inherited value in grey with the name of the environment it comes from. Click it to set a value of its own. The column header shows the parent. - A script that calls `pm.environment.set` writes to the environment in use, never to its parent. `pm.environment.unset` removes the environment's own value, so the inherited one applies again. - **+ Variable** adds the new variable only to environments that inherit from nothing; the others pick it up from them. - An environment under a protected one is protected too. - Deleting a parent moves the environments that inherited from it up to the parent's own parent, or leaves them on their own. - Postman has no inheritance, so **Export…** writes the environment with the inherited values included. The parent is saved as `parentId` in the environment's file. ## Importing a .env file To copy variables from an existing `.env` file, open an environment and choose **Import .env** in its **•••** menu. The file picker shows hidden files, so `.env` and `.env.local` are listed; pick one from any folder. Each `KEY=value` line becomes a variable in the environment, and a variable that already exists takes the value from the file. `export` prefixes, `#` comments and quoted values are understood. The values are copied once: later edits to the file do not reach Kurlo, so import it again after changing it. Mark the imported tokens and passwords as **Secret** so they stay out of the workspace files. ## Switching environments Use the environment switcher in the title bar. The active environment is per-workspace — switching to a different workspace remembers its last-used environment. When a workspace has more than eight environments, the switcher opens with a search field: type part of a name and press Enter to switch to the first match. The list scrolls, and **Manage environments** stays at the bottom. # Pin an environment to a collection Source: https://kurlo.dev/docs/guides/environments/pin/ ## Pinning environments to a collection When one workspace holds several services, pin each collection's environments to it so the switcher shows only those while you work in that collection. 1. Open the collection's settings and go to **Overview**. 2. Under **Environments**, click **Pin an environment…**, type to search and pick one. Repeat for every environment that belongs to this collection. 3. Click **Set as default** next to the one to select when you open the collection. Without a choice, the first pinned environment is the default. Only pinned environments are listed there. Click **×** next to one to unpin it. While a request from that collection or its settings are open: - The switcher lists **No environment**, then the pinned environments. The rest of the workspace sits under **Other environments**, collapsed. You can still pick one from there. - Opening the collection selects its default environment, unless the active one is already pinned to it. A short message says which environment is now in use. - If you pick another environment while you stay in the collection, Kurlo keeps your choice. - When you move on to a collection without pinned environments or to a new request, Kurlo switches back to the environment you had before you opened the pinned collection. If you picked an environment from **Other environments** while inside, it stays. Collections without pinned environments list every environment, as before. An environment can be pinned to several collections. Deleting an environment unpins it everywhere. Pins are saved in `collection.yml` as `environmentIds` and `defaultEnvironmentId`. They only change the app's switcher: `kurlo run` and `kurlo mcp` still use the environment you name. # Variables from scripts Source: https://kurlo.dev/docs/guides/environments/scripts/ ## Setting variables from scripts ```js // Use in a test script after parsing a login response: const body = pm.response.json() pm.environment.set("authToken", body.access_token) pm.environment.unset("authToken") // Runtime-scoped: pm.variables.set("traceId", "kurlo-" + Date.now()) ``` A common pattern: a "login" request fetches a token and stores it under `authToken`. Every other request uses `Authorization: Bearer {{authToken}}` and inherits the value. # Secret variables and environment safety Source: https://kurlo.dev/docs/guides/environments/secrets/ ## Secret variables Mark a variable as **secret** in the environment editor — its value is masked in the UI and excluded from collection exports. Useful for tokens and keys. ## Deleting an environment Choose **Delete** in the environment's **•••** menu. Children that inherit from it move to its parent, and collections unpin it. Click **Undo** in the message that follows, or use the trash button in the **Environments** header until you quit Kurlo, to bring it back with its children and pins. See [Restoring deleted items](https://kurlo.dev/docs/guides/workspaces/starred/#restoring-deleted-items). ## Coloring an environment Give an environment a color so you notice which one is in use, for example red for production. Open the environment, click **•••** and pick a color under **Color**: red, amber, green, blue or gray. **No color** removes it. The color tints the environment switcher in the title bar while that environment is in use and marks it in the environment list, the switcher menu and the **Matrix** column header. The colors follow the active theme. The color is saved in the environment file as `color`, so a Git-backed workspace shares it with your team, and `kurlo mcp` lists it, so a connected assistant can tell which environment is marked. ## Protecting an environment from AI agents Choose **Protect from AI agents** in an environment's ⋯ menu to keep assistants connected through [`kurlo mcp`](https://kurlo.dev/docs/guides/mcp-server/permissions/#protected-environments) away from it. They can still see that it exists, but they cannot send requests with it or change its variables. The environment shows a **Protected** badge, and the mark is saved in its file, so a Git-backed workspace shares it with your team. Use it for production. ## Sandbox environments for the agent Choose **Sandbox for the agent** in an environment's ⋯ menu for an environment that points at disposable data, such as a local stack or a test tenant. The Kurlo agent then sends every request with it without asking, including `POST`, `PUT`, `PATCH` and `DELETE`. The environment shows a **Sandbox** badge and the mark is saved in its file. A protected environment cannot be a sandbox. See [What the agent may do without asking](https://kurlo.dev/docs/guides/agent/approvals/#what-it-may-do-without-asking). # Global variables and saving Source: https://kurlo.dev/docs/guides/environments/global/ ## Global variables **Environments → Globals** holds variables that apply to every request in every workspace. They are the lowest-priority scope: an environment (or collection) value with the same name wins. Use them for values that are not tied to one environment — a personal API key, a machine-specific port, or something a script produced that later requests need. Scripts read and write them with [`pm.globals`](https://kurlo.dev/docs/reference/scripting-api/variables/), and a value written during a send shows up in the editor once the request finishes. Globals are saved with your local data rather than in the Git-backed workspace YAML, so they do not travel to teammates in a shared repository. ## Manual save vs autosave Environment edits follow the same save mode as requests: - **Autosave on:** edits persist after the [autosave delay](https://kurlo.dev/docs/guides/settings/saving/) from your last change. - **Manual save:** renaming an environment, changing **Inherits from**, editing variables in either view and **Import .env** mark the environments unsaved. They reach the disk only when you click **Save** or press the save shortcut, and **Revert** puts back the saved version. Other actions that write the workspace, such as switching the environment in use or creating one, leave the unsaved edits alone. **Protect from AI agents**, **Sandbox for the agent** and **Delete** in the **•••** menu apply right away in both modes. Global variables follow the same rules, with their own **Save** and **Revert**. Script updates from `pm.environment.set(...)` are merged back into the active environment after a request or runner execution. # Git-backed workspaces Source: https://kurlo.dev/docs/guides/git-workspaces/ > Store Kurlo workspaces as YAML files, keep secrets local, and collaborate through Git. Kurlo can store workspace data in a folder instead of only inside the encrypted app profile. When that folder is a Git repository, the workspace becomes reviewable, branchable, and shareable with a team. # Set up a Git workspace Source: https://kurlo.dev/docs/guides/git-workspaces/setup/ ## When to use Git storage Use a Git-backed workspace when you want: - API collections reviewed in pull requests. - Stable YAML files instead of opaque JSON exports. - Local-only secrets. - Branches for API changes. - Diff, conflict, commit, pull, and push workflows inside Kurlo. Use the default app storage when the workspace is private, short-lived, or not meant to be shared. ## Requirements Kurlo runs the `git` command rather than bundling its own, so Git storage needs Git installed and on the PATH: - **Windows** — install [Git for Windows](https://git-scm.com/downloads); Windows ships none. - **macOS** — run `xcode-select --install`. `/usr/bin/git` exists on a clean Mac but is only a stub until the Command Line Tools are installed. - **Linux** — install `git` from your distribution's package manager. Restart Kurlo after installing. Without Git, Kurlo says so on the Git screen and the folder still works as a local (non-Git) workspace — collections, environments, and requests all behave normally; only branches, commits, and remotes are unavailable. ## What Kurlo writes Shared files: ```text kurlo.yml .gitignore kurlo-agent.md workspaces/**/*.yml workspaces/*/README.md ``` The shared YAML contains workspaces, collections, explicit folder paths, requests, environments, defaults, scripts, and settings. Secret values are replaced with `{{kurloSecret:...}}` placeholders. Their real values stay in Kurlo's encrypted local `requests.json` profile instead of the Git workspace. See [Kurlo YAML format](https://kurlo.dev/docs/reference/kurlo-yaml-format/) for the public schema. `kurlo-agent.md` holds the team's notes for the agent, if the workspace has them; see [Team notes in kurlo-agent.md](https://kurlo.dev/docs/guides/agent/team-notes/#team-notes-in-kurlo-agentmd). Kurlo lists it under Changes and commits it with the rest of the workspace. `workspaces//README.md` is the workspace README shown on the workspace overview, matched in any letter case (`Readme.md` works too). Kurlo lists it under Changes and commits it with the rest of the workspace, so a README a teammate pushes shows up after you pull. # Open or clone a workspace Source: https://kurlo.dev/docs/guides/git-workspaces/open/ ## Starting a folder workspace 1. Click **Local storage** in the status bar to open the Git and storage screen. 2. Choose **New folder workspace…** and name the folder. 3. Select **Create empty workspace** or **Copy current workspaces**, then click **Create** and pick the parent directory. Kurlo writes the workspace YAML files into the new folder. 4. To track the folder with Git, choose **Init Git here**. Add a remote when you are ready to share. Kurlo only manages its own files. Other project files in the same repository are left alone. ## Opening or cloning On the Git and storage screen, choose **Open existing repo** to pick a local Git repository, or **Clone from URL** to download one into a new folder. To open an existing Kurlo folder workspace directly, use **Open a workspace** on the welcome screen. Kurlo reads the YAML store, merges local secrets where available, and shows diagnostics for any files it could not load. When the workspace uses secrets this computer does not have yet — after a clone, or on another machine — Kurlo lists them grouped by where they are used: each request by name, method and location, each collection and environment by name, and saved cookies by cookie name. Fill in the values you need now and choose **Later** for the rest; empty ones can be added where they are used. If the folder is missing or moved, Kurlo enters recovery mode and lets you choose another folder, open an existing repository, or clone again. # Daily Git flow Source: https://kurlo.dev/docs/guides/git-workspaces/workflow/ Open the Git workspace screen from the branch at the left of the status bar. The status bar also shows commits to push and pull (↑ ↓), how many Kurlo files changed, and a flag while a merge or rebase is in progress or when the tracked remote branch is gone. The screen covers the common loop: 1. **Fetch** to update remote refs. 2. **Pull** using fast-forward, merge, or rebase strategy. 3. Edit requests, environments, folders, and collection defaults in Kurlo. 4. Review changed YAML files and diffs. 5. Stage selected files or all Kurlo files. 6. Commit with a message. 7. Push to the configured upstream. Kurlo shows ahead/behind counts, current branch, upstream status, remotes, stashes, changed files, commit history, and outgoing commits. A diff of more than 1,500 lines, such as a commit that imports a large collection, renders only the lines near the screen as you scroll, so it opens and scrolls without freezing. In such a diff the file names scroll with the lines instead of staying pinned at the top. The **History** tab loads older commits by itself as you scroll toward the end of the list, so long histories read as one list. If loading fails, the end of the list says so and offers **Retry**. Once a branch is pushed and has nothing left to push, **Create PR** appears next to **Push**. It opens the page that starts a pull request on GitHub, or a merge request on GitLab and Bitbucket, from the current branch into the remote's default branch. Kurlo builds the link from the remote URL and sends nothing itself; for other hosts it says it cannot build one. ## Branches and stashes Branch tools include: - Checkout local or remote branches. - Create a branch from current HEAD or from a remote branch. - Rename and delete branches. - Pull a specific branch. - Set tracking/upstream where needed. Stash tools are available when local changes would block a pull or branch operation. You can stash, pop a stash, or let Kurlo offer an autostash-style flow before pulling. # Conflicts and diagnostics Source: https://kurlo.dev/docs/guides/git-workspaces/conflicts/ ## Conflicts When Git reports conflicts, Kurlo blocks normal workspace editing until the conflict is resolved. The conflict resolver can: - Show ours/theirs versions. - Parse inline conflict markers. - Step through unresolved hunks. - Accept ours, accept theirs, or edit the merged result. - Continue or abort the Git operation. This is intentionally conservative: Kurlo would rather pause than silently overwrite workspace YAML. ## Diagnostics Diagnostics appear when YAML exists but is incomplete, invalid, or references something Kurlo cannot load cleanly. A diagnostic does not always mean data is lost; often it means a third-party edit missed a required field. The Git screen lists problems from every workspace in the folder, not only the open one, and names the workspace each problem locks. A file Kurlo cannot read is never rewritten or deleted while it is broken; the rest of the workspace saves as usual. Use diagnostics to jump to the affected workspace, collection, request, or environment. After you fix a file with **Edit YAML**, the workspace reloads by itself. # Changes made outside Kurlo Source: https://kurlo.dev/docs/guides/git-workspaces/external-changes/ A folder or file is always named after the workspace, collection, request, or environment it holds, so paths in Git read like the names in the app. When a name changes, in the app, by editing the YAML, or in a pulled commit, Kurlo moves the file on its next save and Git shows a rename under Changes; commit it like any other change. Opening or pulling never moves files by itself. An object's ID never changes with its name. Folders decide what belongs where. A collection belongs to the workspace folder it sits in, a request to its collection folder, and an environment to its workspace folder. The `workspaceId`, `collectionId`, and `requestId` fields in child files are copies of that. If they disagree with the folder, Kurlo follows the folder and corrects the field as soon as it loads the folder, changing only that line. Changing an ID in `workspace.yml` or `collection.yml` therefore needs no other edits: commit the corrected files Kurlo shows under Changes together with your change. Moving a folder moves everything inside it. Order lists such as `workspaceOrder`, `collectionOrder`, and `requestOrder` only set the order. An entry for a file that no longer exists is skipped. When exactly one ID in a list changed, Kurlo replaces the old entry with the new one so the order stays the same. Some changes leave Kurlo unable to tell which file is right, and these pause saving: - Two objects of the same kind share an ID, usually because a folder was copied. Kurlo reports the copy once and keeps showing the original. - An object has no ID. - `kurlo.yml`, `workspace.yml`, or `collection.yml` was deleted but files inside its folder remain. - A response example has no matching request file. Response examples are read in the background just after a workspace opens. If one of them turns out to be unreadable, Kurlo refuses to save until it reloads the workspace, which it does by itself, and then lists the file like any other problem. When this happens, the Git screen lists one entry per problem and pauses editing and commits for the open workspace folder. Fix the listed file with **Edit YAML**, or pull a commit that fixes it. Kurlo does not guess a replacement. ## Safety rules - Kurlo does not write real secret values into managed workspace YAML. Tokens, passwords, client secrets, AWS keys and session tokens, OAuth 2.0 refresh tokens and private keys, and the client-certificate passphrase are all replaced by a `{{kurloSecret:…}}` placeholder in the file. - Local secret values remain in the encrypted Kurlo profile and are not staged by the Git workspace UI. - Kurlo does not discard unrelated repository files. - Destructive actions such as discard and force-push are explicit UI actions. - Pull, checkout, stash, commit, discard and conflict resolution wait while `kurlo mcp` or another Kurlo process is writing the workspace, so a commit never captures half of an agent's batch of changes. - Unknown YAML fields are preserved where possible so future versions and third-party tools can coexist. # Import & export Source: https://kurlo.dev/docs/guides/import-export/ > Import collections, API specs, and individual requests. Compare export formats for sharing or backup. Kurlo supports both one-off interchange formats and full Kurlo backups. Imports are non-destructive unless you explicitly choose the all-data restore path. ## Supported sources | Source | What Kurlo imports | |--------|--------------------| | Postman Collection v2.0 / v2.1 | Collections, nested folders, requests, auth, bodies, GraphQL, scripts, collection variables, and request documentation. Environment and globals exports import through the same picker. | | Postman Collection v3 (folder) | Postman v12 Native Git folders of `.request.yaml` files: collections, folders and their order, HTTP, GraphQL, gRPC, WebSocket, Socket.IO and MCP requests, auth, bodies, scripts, settings, examples, environments and globals. | | Insomnia v4 JSON | One collection per file with requests, their folder paths, and supported auth, bodies, and scripts. Folder environment values become request variables. | | Bruno/OpenCollection | Collections, explicit empty folders, supported request types, and metadata. See [protocol support by format](https://kurlo.dev/docs/guides/request-types/portability/). | | OpenAPI/Swagger | From a file or a URL. HTTP/SSE requests generated from operations, plus the collection defaults that make them sendable: the server becomes a `{{baseUrl}}` variable, path parameters become the request's path variables seeded from the spec's examples, and declared security schemes become the request's auth. | | HAR | Captured HTTP requests. | | `.http` / `.rest` | JetBrains HTTP Client and VS Code REST Client files: requests, names, headers, bodies, and file variables. | | cURL | A single request pasted into the URL bar, including the flags that map onto a request setting — `-k`, `--max-time`, `--proxy` — and a form part's `;type=`. | | Kurlo all-data backup | Workspaces, collections, environments, requests, history, cookies, and selected UI/request preferences. | | Kurlo Git/YAML workspace | Reviewable workspace files with local-only secrets. | # Postman collections Source: https://kurlo.dev/docs/guides/import-export/postman/ ## From Postman Kurlo reads both Postman formats and tells them apart on its own: - **v2.0 / v2.1** — the single JSON file Postman exports. Both versions go through the same **Postman collection** option, so there is no version to choose. - **v3** — the folder of YAML files Postman v12 uses for local collections (Native Git). Use it to import native gRPC, WebSocket, Socket.IO, and MCP requests. See [Postman v3 folders](#postman-v3-folders). 1. In Postman: right-click the collection → **Export** → choose v2.1. 2. In Kurlo, click **Import collection** in the sidebar. Select **Postman collection**, click **Import**, then pick the JSON file. You can also drop the file into the window. 3. Kurlo creates a new collection in the current workspace, preserving the folder tree. What carries over: - Folder hierarchy — including folders that hold no requests — request names, methods, URLs. - Headers, query params, path variables (`:id` and its value), body (JSON, form-data, raw, urlencoded). - Pre-request and test scripts. They always go to Kurlo's JavaScript fields, even when Tengo is the selected [script engine](https://kurlo.dev/docs/guides/settings/script-engine/): switch to JavaScript to run them. - Request descriptions, which become the request's **Docs** tab. - Collection-level variables, auth, and scripts, which become the collection's [defaults](https://kurlo.dev/docs/guides/collection-defaults/). A request that declared no auth of its own is set to **Inherit auth**, so the collection's auth applies exactly as it did in Postman. - The whole OAuth 2.0 configuration, not just a stored access token: grant type, authorization and token URLs, client id and secret, scope, audience, and refresh token. Postman folders can carry their own auth and scripts. They become the folder's [defaults](https://kurlo.dev/docs/guides/collection-defaults/folders/), so every request in the folder still runs them, and you change them in one place. Exporting to Postman writes them back to the folder. In a v3 export, inherited headers are applied to the individual HTTP and GraphQL requests. The v2.1 export leaves inherited headers out. ### Environments and globals Postman exports environments and globals as separate JSON files. Pick **Postman collection** in the import dialog and choose one of those files — Kurlo recognises it and imports it as an environment (made active) or merges it into **Globals**. Values Postman marked as secrets stay marked as secrets. ### Postman v3 folders Postman v12 stores a collection as a folder: each request is a `*.request.yaml` file, folder and collection settings live in `.resources/definition.yaml`, and saved responses in `.resources/.resources/examples/`. In the import dialog, select **Postman v3 collection folder**, click **Import**, and choose the folder. You can also drop the folder into the Kurlo window. Dropping a single `.request.yaml` file imports just that request. You can pick a single collection folder or the whole `postman/` folder of a repository. Kurlo finds every collection inside it, imports each one as its own collection, and also imports the environments (`*.environment.yaml`) and globals (`*.globals.yaml`) next to them. A folder with no `definition.yaml` at all becomes one collection named after the folder. What the v3 folder import keeps: - The `order` of folders and requests. Items without one go last, sorted by name. - Headers, query parameters, path variables and collection variables written either as a list or as a `key: value` map. - Request settings: SSL verification, redirects, HTTP version, URL encoding and the cookie jar. - gRPC requests with their method, message, metadata and TLS settings; WebSocket requests with their saved messages; Socket.IO requests with their events, the first message to send and every saved message; MCP requests over HTTP with the JSON-RPC call split into method, name and arguments. - Saved examples of HTTP and GraphQL requests. - Scripts written for HTTP requests at collection and folder level. Collection and folder scripts that Postman runs only for gRPC or Kafka are left out, so they cannot run on your HTTP requests. The importer skips Postman MQTT, Kafka, LLM, data, and stdio MCP items and reports the count. Secrets that Postman keeps in a vault import as empty secret variables for you to fill in. What doesn't carry over: - Postman cloud Monitors. Cloud **Mock Servers** do not come across as such, but the saved responses they were built from import as [examples](https://kurlo.dev/docs/guides/examples/), which Kurlo's own [mock server](https://kurlo.dev/docs/guides/mock-server/) serves locally. - Visualizer scripts. - Variable types beyond string/secret. ## Export to Postman v3 1. In Kurlo, open the collection's **⋯** menu and choose **Export…**. Select **Postman collection v3 (YAML folder)** and click **Export**. 2. Name the new folder and select its parent directory. Kurlo writes the collection under `postman/collections/` inside the new folder. 3. In Postman Desktop, go to **Workspaces → Local Files → Open Folder** and select the new folder itself. The collection appears under **Local Files**. See [Postman's local folder instructions](https://learning.postman.com/latest-v-12/docs/use/native-git/sync#connect-a-project-folder). HTTP, GraphQL and gRPC open as native requests. SSE uses an HTTP GET request with `Accept: text/event-stream` by default. If the collection contains other request types, Kurlo shows how many will be skipped before writing the folder. gRPC exports include the method, JSON message, metadata, TLS settings, and server reflection setting. If reflection is unavailable, add the service's `.proto` files in Postman before invoking the method. Files from your machine, including protobuf sources and client certificates, are outside the export. For a GraphQL document with several operations, choose the operation in Postman. The export includes collection variables and supported auth and JavaScript hooks. Environments, globals and saved response examples are outside the v3 export. If Kurlo detects secret values, the export dialog lets you choose whether to include them. ## Export to Postman v2.1 Choose **Postman collection v2.1** to export a single JSON file. The file stores a gRPC request's method, message and metadata in `x-kurlo` for re-import into Kurlo. Use the v3 folder to open gRPC as a native request in Postman. # Import OpenAPI or Swagger Source: https://kurlo.dev/docs/guides/import-export/openapi/ ## From OpenAPI / Swagger Select **OpenAPI / Swagger** in **Import collection**, click **Import**, and choose a JSON or YAML spec. Kurlo builds one request per operation, grouped into folders by the operation's first tag, with the summary as the request name and the description as its Docs tab. The YAML that spec generators such as Jackson and springdoc write is read as is, including lists at the same indent as their key, quoted strings that continue over several lines and `[...]` or `{...}` collections split over several lines. A YAML file with several documents separated by `---` is rejected with a message rather than merged. The point is a collection you can send straight away, so three things land on the collection rather than being baked into each request: - **Servers** become a `baseUrl` variable, as in Bruno, and every request URL starts with `{{baseUrl}}`. Servers declared on the document go to the collection's **Vars** tab. Servers declared on a path or operation go to that request's [**Vars**](https://kurlo.dev/docs/guides/environments/request-variables/) tab instead; the operation's list wins over the path's. A request whose servers match the document's has no row of its own. The first server is switched on; alternatives such as Sandbox are switched-off `baseUrl` rows, and the description of each row names the server, for example *Sandbox server from the spec*. To switch, untick the first row and tick the alternative. Request variables win over the environment, so a `baseUrl` in an environment changes only requests without their own row. Server template variables use their defaults or first enum value; a missing value stays a `{{variable}}` for you to fill in. Imports from a URL resolve relative server addresses against the spec URL. - **Path parameters** become [path variables](https://kurlo.dev/docs/guides/request-types/http/#path-variables): `/users/{userId}` imports as `/users/:userId`, with the value seeded from the spec's `example` or `default` in the request's **Params** tab. A parameter that is only part of a segment, such as `/files/{name}.json`, cannot be a path variable and becomes a collection variable instead. - **Security schemes** become auth. A scheme declared for the whole document lands on the collection and each request is set to **Inherit auth**; an operation with its own `security` carries that instead, and `security: []` means the operation is public. HTTP basic, digest and bearer, API keys (with the name and location the spec gives), and OAuth 2.0 (with its token and authorization URLs and scopes) are mapped. The credentials themselves are not in a spec, so each one points at a collection variable — `{{bearerToken}}`, `{{apiKey}}`, `{{oauth2ClientSecret}}` — giving you one place to fill in. `openIdConnect` is left as **No auth**: its endpoints can only be discovered by fetching the provider's configuration, which the importer does not do. Declared `responses` come across as [examples](https://kurlo.dev/docs/guides/examples/), including a body derived from the response schema when the spec writes none — which means an imported spec can drive the [mock server](https://kurlo.dev/docs/guides/mock-server/) straight away. ### From a URL Select **OpenAPI / Swagger from URL** in **Import collection** and click **Import**. Paste the link in **Import from URL** and click **Import** again. A spec URL is what teams actually pass around, because it is the one that stays current, and Kurlo builds exactly the collection the file import would. The document is fetched by Kurlo itself rather than by the embedded browser, so a spec host that sends no CORS headers still works, redirects are followed, and your [proxy](https://kurlo.dev/docs/guides/proxy/) and TLS settings apply. A link with no scheme is read as `https`, and no cookies are sent. If the server uses a self-signed, internal or expired certificate, tick **Skip TLS certificate check** in the same dialog. Kurlo then fetches the spec without verifying the certificate, so anyone between you and the server could change what you import: use it only for a server you trust. The box applies to that one import and is unticked every time the dialog opens; when a certificate is rejected, the error message points to it. **Keep in sync with this URL** is ticked by default. Kurlo then remembers the URL, checks it for changes and shows them for review before anything changes. See [OpenAPI sync](https://kurlo.dev/docs/guides/openapi-sync/). The collection is named from the spec's `info.title`. When the spec has none, Kurlo falls back to the host rather than to a path segment like `/v3/api-docs`, which names the format instead of the API. One mistake is common enough to name: **linking to the Swagger UI page rather than the document it renders**. The page is HTML, and Kurlo says so and points at where the document usually lives — `/swagger.json`, `/openapi.json` or `/v3/api-docs` — instead of reporting a parse failure. # Import .http or .rest files Source: https://kurlo.dev/docs/guides/import-export/http-files/ ## From a `.http` / `.rest` file Select **.http / .rest file** in **Import collection**, click **Import**, and choose the file. Kurlo reads the format shared by the JetBrains HTTP Client and the VS Code REST Client: ```http @baseUrl = https://api.example.com ### List orders GET {{baseUrl}}/orders?status=open Accept: application/json ### Create order # @name createOrder POST {{baseUrl}}/orders Content-Type: application/json { "sku": "KURLO-1" } ``` - `###` separates requests, and the text after it becomes the request name. A `# @name` directive takes priority. - File variables (`@baseUrl = …`) become collection variables, so `{{baseUrl}}` keeps resolving after import. - A bare URL line is treated as `GET`, and a trailing `HTTP/1.1` is ignored. - `WEBSOCKET` requests and the `X-REQUEST-TYPE: GraphQL` header map to Kurlo's WebSocket and GraphQL request types. - JetBrains pre-request scripts (`< {% … %}` above the request line) and response handlers (`> {% … %}` after the body) become the request's pre-request and post-response scripts. They keep running as written: Kurlo's script sandbox understands the JetBrains `client`, `request` and `response` objects (see [JetBrains HTTP Client globals](https://kurlo.dev/docs/reference/scripting-api/compatibility/#jetbrains-http-client-globals)). - `< ./body.json`, `> ./handler.js` and `>> ./out.json` reference files the importer cannot read. Kurlo records them in the request's Docs tab instead of dropping them silently. You can also drop a `.http` or `.rest` file anywhere in the Kurlo window to import it. # Import a cURL command Source: https://kurlo.dev/docs/guides/import-export/curl/ ## From curl Paste a curl command directly into the URL bar of a new request. Kurlo parses: - Method (`-X`) - Headers (`-H`) - Body (`-d`, `--data-raw`, `--data-binary`) - File uploads (`-T`), sent as a binary body with `PUT` - Query parameters (`--url-query`) - Auth: Basic (`-u`), Digest (`--digest -u`), NTLM (`--ntlm -u`), Bearer (`--oauth2-bearer`) and AWS Signature v4 (`--aws-sigv4`) - Multipart fields (`-F`) Combined short flags such as `-sSL` or `-sSLo out.json` are read the way curl reads them. URL-only curl commands work too — `curl https://api.example.com/users` becomes a GET request. When a command uses an option Kurlo cannot carry over, such as headers read from a file (`-H @headers.txt`) or `--negotiate`, the paste stops with a message naming the option instead of importing a request that would send something different. # Import from Bruno Source: https://kurlo.dev/docs/guides/import-export/bruno/ ## From Bruno/OpenCollection Kurlo imports OpenCollection-style folders and request files. Empty folders are preserved explicitly, so a folder can exist before it contains a request. Headers, auth, and scripts in a `folder.yml` or Bruno `folder.bru` become that folder's [defaults](https://kurlo.dev/docs/guides/collection-defaults/folders/); a folder without an auth block inherits. Request variables come across to the request's [**Vars**](https://kurlo.dev/docs/guides/environments/request-variables/) tab: `vars:pre-request` and `vars:post-response` in `.bru` files, `runtime.variables` and `set-variable` actions in YAML. Kurlo has no folder variables, so a folder's variables are copied into the Vars tab of every request in it; a request's own variable with the same name wins. Collection variables from `vars:pre-request` in `collection.bru` or `request.variables` in `opencollection.yml` become collection variables. Kurlo's OpenCollection export writes: - `folder.yml` files for explicit folder paths, with the folder's headers, auth, and scripts. - HTTP, GraphQL, gRPC, WebSocket, and Socket.IO request records. Import and export for these types are covered by Kurlo round-trip tests. Check the imported request in Bruno when sharing between clients. - Request-level scripts, settings, auth, params, headers, and bodies where the format supports them. - Request variables as `runtime.variables` and post-response variables as `set-variable` actions, which Bruno reads back into its Vars tab. Postman and Insomnia have no request variables. A Postman export writes Pre Request variables as `pm.variables.set(...)` lines at the top of the pre-request script, so the request behaves the same in Postman. Variables in an Insomnia folder's environment are copied into the Vars tab of every request in the folder. Both exports also keep the variables in Kurlo's own field, so they import back into Kurlo unchanged. # Export and share Source: https://kurlo.dev/docs/guides/import-export/export/ ## Git-backed YAML workspaces For team sharing, prefer Kurlo's Git/YAML storage over repeated JSON exports. It stores workspace state as plain YAML files: - `kurlo.yml` and `workspaces/**/*.yml` are shared. - Sensitive values become `{{kurloSecret:...}}` placeholders; the real values remain in Kurlo's encrypted local profile outside the repository. - Folder hierarchy is represented by `request.folderPath` plus `collection.folderPaths`, so empty folders survive round-trips. See [Kurlo YAML format](https://kurlo.dev/docs/reference/kurlo-yaml-format/) for the public contract. ## All-data backups Use **Settings -> General -> Data -> Export all data** for a Kurlo-to-Kurlo profile backup. Unlike collection interchange formats, it includes history, cookies, all local workspaces, and selected preferences. The file is plaintext and can contain secrets. Import replaces the current local profile rather than merging it. See [Backup & recovery](https://kurlo.dev/docs/guides/backup-recovery/) for the exact contents, exclusions, recovery-key behavior, and a safe restore procedure. ## Export Open the collection's **⋯** menu and choose **Export…**. The picker offers Postman v2.1 JSON and v3 YAML, Insomnia Export v4 JSON, OpenAPI 3.0 JSON, Swagger 2.0 JSON, and OpenCollection YAML. Choose [Postman collection v3 (YAML folder)](https://kurlo.dev/docs/guides/import-export/postman/#export-to-postman-v3) to transfer native gRPC requests into Postman Desktop. The v2.1 option writes a single JSON file for Postman's file importer. See [protocol support by format](https://kurlo.dev/docs/guides/request-types/portability/) for the full list. Secrets marked as **secret** are stripped, redacted, or kept as Kurlo secret placeholders depending on the target format. Git/YAML workspaces keep the real values in Kurlo's encrypted local profile, outside shared files. ## Sharing within a team For day-to-day collaboration: 1. Use Git-backed YAML workspace storage. 2. Commit `kurlo.yml`, `.gitignore`, and `workspaces/**/*.yml`. 3. Keep `{{kurloSecret:...}}` placeholders intact; Kurlo resolves them from each user's encrypted local profile. 4. Use import/export formats only for interoperability with another client. For environment-specific variables, keep non-secret defaults in the workspace and put real secret values in local secrets. # OpenAPI sync Source: https://kurlo.dev/docs/guides/openapi-sync/ > Keep a collection in step with an OpenAPI spec from a URL or a file, review every change before it lands, and check for drift in CI. A collection imported from an OpenAPI spec goes stale as soon as the API changes. OpenAPI sync keeps a link to the spec and shows you what changed: new endpoints, changed parameters, bodies and docs, and endpoints that are gone. Nothing changes until you review it, and your own edits, scripts and tests stay yours. There is no limit on how often you sync. # Connect an OpenAPI spec Source: https://kurlo.dev/docs/guides/openapi-sync/connect/ ## Connecting a collection There are two ways in: - **When you import.** **Import collection → OpenAPI / Swagger from URL** has **Keep in sync with this URL** ticked by default. The new collection is linked to that URL straight away. - **For an existing collection.** Open the collection's **•••** menu and choose **OpenAPI sync…**, or open its settings and the **OpenAPI** tab. Enter the spec's URL, or a file path relative to the workspace folder, such as `../api/openapi.yaml` in a monorepo, and click **Connect**. **Choose file…** picks a file. The source and its request headers can use `{{variables}}` from the collection and the active environment, for example `https://{{host}}/v3/api-docs` with `Authorization: Bearer {{specToken}}`. Keep tokens in a secret variable rather than in the header itself, because the source settings are saved in `collection.yml`. **Skip TLS certificate check** is there for specs served with a self-signed or internal certificate. When you connect a collection that was imported earlier, requests are matched to operations by method and path. `{{baseUrl}}` and the host are ignored, and `:id`, `{id}` and `{{id}}` count as the same parameter. Requests that match nothing are left alone. ## Checking for changes The **OpenAPI** tab shows whether the collection is in sync and when the spec was last checked. Click **Check now** to check the spec. When Kurlo already knows about pending updates, the button reads **Review changes**. Kurlo also checks on its own while the app is open, every 15 minutes by default. Change it with **Check for updates**: off, every 5 or 15 minutes, every hour, every 6 hours or once a day. A minimized window does not check; the check runs when you come back. Kurlo sends `If-None-Match` and `If-Modified-Since`, so a server that supports them answers `304 Not Modified` and nothing is downloaded or compared. When an automatic check finds changes, a dot appears next to the collection in the sidebar and a short message says what changed. Click the dot to open the tab. # Review OpenAPI changes Source: https://kurlo.dev/docs/guides/openapi-sync/review/ ## Reviewing changes The review groups the changes: | Group | What it means | Ticked by default | |-------|---------------|-------------------| | **New** | Operations added to the spec. They are added to the folder of their first tag. | Yes | | **Changed** | Only the spec changed these fields, so Kurlo takes the spec's version. | Yes | | **Conflicts** | You and the spec both changed the same field. **Keep mine** or **Use spec** per endpoint. | Yes, keeping yours | | **Removed from the spec** | Requests whose operation is gone. Ticked ones go to **Recently deleted**. | No | | **Collection settings** | The `baseUrl` server variable or the collection's auth scheme changed. | Yes | Click a row to see each field side by side: yours and the spec's. **Apply** applies the ticked rows, **Accept all** applies every row and takes the spec's side in conflicts, and **Skip this version** hides the change until the spec changes again. A new endpoint you leave unticked is remembered in the collection's `ignored` list and not offered again. An endpoint whose request you deleted yourself is not offered again either. # What sync compares Source: https://kurlo.dev/docs/guides/openapi-sync/comparison/ For each request linked to an operation, sync compares the method and URL, query parameters, path parameters, headers, the body, the auth type, the Docs tab and the examples that came from the spec. It never touches pre-request and test scripts, assertions, request settings, request variables or examples you saved yourself. The comparison is three-way. Kurlo keeps the spec from the last applied sync and compares both your request and the new spec with it: - Only the spec changed a field: the spec's version is taken. - Only you changed it: yours stays. - Both changed it: it is a conflict, and yours stays unless you pick the spec. Parameters and headers are compared row by row. A new row from the spec is added, a row the spec dropped is removed unless you changed its value, and rows you added yourself stay. A value you replaced with a `{{variable}}` is your change and is kept. The body is compared as a whole. When an operation moves to a new path but keeps its `operationId`, sync treats it as a URL change of the same request rather than a removed and a new endpoint, so the request keeps its scripts and tests. The first sync of a collection has no earlier spec to compare against. Every difference between your requests and the spec is then shown as a conflict, with your version kept by default. # OpenAPI sync in CI and teams Source: https://kurlo.dev/docs/guides/openapi-sync/automation/ ## Files and teams The spec from the last applied sync is saved as `openapi/spec.json` next to `collection.yml`, and each linked request stores its operation as `openapi: GET /users/{id}`. Commit both with the collection: a teammate who pulls then sees the same changes you would, instead of every request looking edited. The fields are listed in the [YAML format reference](https://kurlo.dev/docs/reference/kurlo-yaml-format/collection/#openapi-source). The last check time, the `ETag` and a skipped version are kept on your computer only. **Disconnect** removes the source and `openapi/spec.json`. Requests keep their `openapi` links, so connecting the same spec again matches them at once. ## In CI and for agents `kurlo openapi check` compares the current spec with `openapi/spec.json` and exits with `1` when the spec has moved on, so a pipeline can flag drift. See [Contract drift](https://kurlo.dev/docs/guides/cli-runner/openapi/#contract-drift-with-kurlo-openapi-check). The `check_openapi_sync` tool of [`kurlo mcp`](https://kurlo.dev/docs/guides/mcp-server/) gives an assistant the same report. ## Limits - Only HTTP requests take part. GraphQL, gRPC, WebSocket and other request types in the collection are left alone. - Request names and folders are set when an endpoint is added and are not changed by later syncs. - Changes are always reviewed; there is no option yet to apply them without the review. # Backup & recovery Source: https://kurlo.dev/docs/guides/backup-recovery/ > Back up or restore a profile, make copies of external workspaces, and recover encrypted data with its matching key. Kurlo has three complementary protection layers: | Method | Best for | Important limitation | |--------|----------|----------------------| | All-data JSON export | Moving a Kurlo profile or creating a portable restore point | Plaintext file containing secrets; selected preferences only. | | Closed-app filesystem backup | Exact recovery of local app data | `requests.json` and its matching key must stay together. | | Git-backed workspace | Team sharing and version history for workspace YAML | Does not include local history, cookies, or real secret values. | # Export all data Source: https://kurlo.dev/docs/guides/backup-recovery/export/ Open **Settings -> General -> Data -> Export all data**. The JSON backup includes: - Workspaces, collections, folders, environments, and saved requests. - Request history and workspace cookie jars. - Collection defaults and request settings. - Theme, autosave mode, shortcut overrides, and request-default preferences. - Global proxy configuration except its password. It does not include: - Unsaved request edits in manual-save mode. - The global proxy password. - External folder or Git repository contents and Git history. - Other local UI preferences, including the selected script engine, default workspace location, and automatic-update preference. :::caution The exported JSON is not encrypted. It can contain auth tokens, OAuth credentials, AWS keys, cookies, and environment values marked secret. Store it like a password file and never commit it to a public repository. ::: # Restore an all-data export Source: https://kurlo.dev/docs/guides/backup-recovery/restore/ 1. Export the current profile first if it is still usable. 2. Open **Settings -> General -> Data -> Import all data**. 3. Select a Kurlo backup JSON file. 4. Confirm the replacement. 5. Re-enter the global proxy password and reconnect any external workspace paths if needed. Import replaces the local workspaces, collections, requests, environments, history, and cookies in the current profile. It is not a merge operation. For cross-machine migration, the all-data export is usually safer than copying encrypted files because it does not depend on an OS credential-store entry. # Filesystem backup Source: https://kurlo.dev/docs/guides/backup-recovery/filesystem/ Quit Kurlo before copying its data directory: | Platform | Default location | |----------|------------------| | macOS | `~/Library/Application Support/Kurlo/` | | Windows | `%APPDATA%\Kurlo\` | | Linux | `~/.config/Kurlo/` or `$XDG_CONFIG_HOME/Kurlo/` | Keep at least these files together: - `requests.json` - encrypted local profile. - `request-store.key` - matching recovery copy of the encryption key. - `request-store.key.dpapi` on Windows, when present. - `request-view.json`, when present - the open tabs and the active request, saved on their own so switching requests does not rewrite `requests.json`. It holds request ids only, and the next full save folds it back into `requests.json`. - `preferences.json` and the rest of the app-data directory for the most complete local restore. Back up folder-backed workspaces and cloned Git repositories separately when they live outside the app-data directory. # Recover an encrypted profile Source: https://kurlo.dev/docs/guides/backup-recovery/recover/ If Kurlo reports **Decryption failed**, restore `requests.json` and the `request-store.key` created with it. The recovery file is owner-readable only and normally has `0600` permissions on Unix-like systems. Kurlo may also find the key in: - macOS Keychain. - Windows DPAPI for the same OS user. - Linux libsecret. The credential-store copy is an additional recovery path, not a substitute for keeping the matching recovery file with a disk backup. :::caution If no matching key copy exists, AES-256-GCM encrypted profile data cannot be recovered. A key from another Kurlo installation will not work. ::: ## Recommended routine 1. Use Git-backed workspaces for shared, reviewable API definitions. 2. Create an all-data export before upgrades, migrations, or destructive imports. 3. Keep periodic closed-app backups of the Kurlo data directory. 4. Verify that external workspace repositories are covered by their own backup or remote. 5. Test restore files in a disposable OS profile when the data is business-critical. See [Privacy & security](https://kurlo.dev/privacy/) for encryption details and [Git-backed workspaces](https://kurlo.dev/docs/guides/git-workspaces/) for repository storage. # Scripting (pre-request & tests) Source: https://kurlo.dev/docs/guides/scripting/ > Pre-request and test scripts in JavaScript or Tengo — inject headers, assert responses, set variables. Kurlo scripts run in a sandboxed JavaScript VM by default. Existing requests can still use the legacy [Tengo](https://github.com/d5/tengo) engine. Both engines share the core `pm.*` API — variables, environment, request mutation, response, tests, expectations and logs — and the 2-second cap (configurable per request). The JavaScript engine also adds collection variables, globals, iteration data, cookies, `pm.crypto` and `pm.sendRequest`. There are two script hooks per request: - **Pre-request** — runs after variable substitution, before the wire send. Use it to inject auth, set query params, log inputs. - **Tests** — runs after the response is received. Use it to assert and to extract values for chained requests. Collection variables set or removed in a pre-request script are available to the test script of the same request. # Pre-request scripts Source: https://kurlo.dev/docs/guides/scripting/pre-request/ ## Anatomy of a pre-request script ```js // Set a trace header for every request pm.request.headers.set("X-Trace", "kurlo-" + pm.variables.get("runId")) // Override the URL conditionally if (pm.environment.get("region") === "eu") { pm.request.set_url("https://eu.api.example.com" + pm.request.url) } ``` # Test scripts Source: https://kurlo.dev/docs/guides/scripting/tests/ ## Anatomy of a test script ```js pm.test("status is 200", () => pm.response.to.have.status(200)) pm.test("response under 500ms", () => pm.expect(pm.response.responseTime).to.be.below(500)) const body = pm.response.json() pm.test("has user id", () => pm.expect(body.user).to.have.property("id")) pm.test("role is admin", () => pm.expect(body.user.role).to.equal("admin")) // Persist for downstream requests pm.environment.set("userId", body.user.id) pm.log("captured userId:", body.user.id) ``` Test results appear in the response **Scripts** panel with pass/fail counts. A `pm.test` in a pre-request script is reported too: it appears in the **Pre-request** block and counts in the collection runner, `kurlo run` and `kurlo mcp`. # Assertions Source: https://kurlo.dev/docs/guides/scripting/assertions/ For checks that need no code, open **Scripts → Assertions** on an HTTP or GraphQL request. Each row is a target, a check and the expected value. The **Add** row inserts common ones: status 200, a 2xx status, a response faster than one second, a JSON content type and a field that exists. | Target | What it reads | |--------|---------------| | `status` | The status code, such as `201`. | | `responseTime` | Total time in milliseconds. | | `size` | Body size in bytes. | | `header.` | A response header, matched without regard to case. | | `body` | The whole body: parsed JSON, or the text when the body is not JSON. | | `body.` or `$.` | A value inside a JSON body: `body.data.id`, `body.items[0].sku`, `body.items[-1]` for the last item, `body["key with spaces"]`. Filters and wildcards are not supported; use a test script for those. | Checks: **equals**, **does not equal**, **is greater than**, **is at least**, **is less than**, **is at most**, **is one of** and **is not one of** (a list such as `200, 201` or `[200, 201]`), **contains** and **does not contain** (text, an array item or an object key), **matches regex**, **exists**, **does not exist**, **is of type** (`string`, `number`, `boolean`, `object`, `array` or `null`) and **has length** (of text, an array or an object). The expected value is read as JSON when it is valid JSON, so `201`, `true`, `null` and `{"a": 1}` compare as values, and as text otherwise. Numbers compare exactly, including integers larger than JavaScript can hold. Header values are always text. `{{variables}}` work in both the target and the expected value. Assertions run after the test script and show up next to its tests, named after the check, such as `status equals 201`, with the reason when one fails, such as `got 404`. A failed request fails every assertion. A request skipped with `pm.execution.skipRequest()` is reported as skipped, and its assertions do not run. The same results count in the collection runner, in `kurlo run` (and its JUnit report) and in `kurlo mcp`. Untick a row to keep it without running it. A request can have up to 200 assertions; the add buttons turn off at the limit. A request file written by hand with more keeps all of them, and they all run. Assertions are saved in the request file as `assertions`. A Postman export turns them into `pm.test` code so Postman runs the same checks; importing that export back into Kurlo restores the rows without doubling the tests. Insomnia and OpenCollection exports leave them out. ## Snippets The **Snippets** row above the editor inserts working code at the end of the current script — setting a variable, adding a header, editing or signing the body, asserting a status, checking a JSON schema. The list follows the active engine, so Tengo requests get Tengo snippets. Hovering a snippet shows the code it will insert. # Build a request body Source: https://kurlo.dev/docs/guides/scripting/request-body/ ## Building the request body A pre-request script can read and rewrite the body that goes on the wire, which is what request signing needs: ```js const payload = pm.request.body.json() payload.nonce = pm.crypto.randomHex(8) pm.request.body.update(JSON.stringify(payload)) pm.request.headers.set("X-Signature", pm.crypto.hmacSha256(pm.request.body.raw, pm.environment.get("secret"))) ``` See [`pm.request.body`](https://kurlo.dev/docs/reference/scripting-api/request/) for the details, including how binary file bodies behave. # Script patterns and limits Source: https://kurlo.dev/docs/guides/scripting/patterns/ ## Common patterns **Chained auth — fetch token in pre-request:** put the login call in a separate request, run it once, persist the token with `pm.environment.set("authToken", ...)`. Downstream requests reference `{{authToken}}`. To do it inline instead, turn on **Allow pm.sendRequest** in the request's Settings tab, call [`pm.sendRequest`](https://kurlo.dev/docs/reference/scripting-api/send-request/) and store the token with `pm.environment.set("authToken", ...)` — a value a pre-request script stores is already used by `{{authToken}}` in the same request. **Conditional skip:** `pm.execution.skipRequest()` in a pre-request script skips the send. It is reported as a skip rather than a failure, so a conditional request does not fail a run or a CI exit code. **Schema checks:** `pm.response.to.have.jsonSchema(schema)` validates the body against a JSON Schema. `tv4` and `require("ajv")` are available for collections that were written against those. **Logging:** `pm.log(...)` writes to the **Scripts** panel. Output is per-request and cleared on next send. ## Limits - 2-second wall clock per script by default, configurable per request up to 60 seconds. - A single regular-expression match stops after 2 seconds. A pattern with lookahead or a backreference that backtracks without end, such as `/^(a+)+(?=b)/` on a long string, no longer hangs the app or a CI run. Under the default 2-second script limit the script then fails with a time-out. - No module imports, process access, filesystem access, or direct network sockets. `require` resolves only [Kurlo's bundled stand-ins](https://kurlo.dev/docs/reference/scripting-api/compatibility/#require) — `lodash`, `ajv`, `tv4`, `uuid`, `crypto-js`, `chai`. - Scripts make HTTP calls only through `pm.sendRequest`, and only when the request opts in. - Tengo uses expression-style assertions: `pm.test("status", pm.response.code == 200)`. - JavaScript supports Postman-style callbacks: `pm.test("status", () => pm.response.to.have.status(200))`. See the full method reference in [Scripting API](https://kurlo.dev/docs/reference/scripting-api/). # Collection Runner Source: https://kurlo.dev/docs/guides/collection-runner/ > Run saved requests as smoke tests, regressions, or data-driven checks. The Collection Runner executes saved requests from a collection or folder and turns the result into a pass/fail report. It is designed for local smoke tests: no account, no cloud monitor, no scheduler. To generate sustained traffic with virtual users or iterations per second, use [load testing with k6](https://kurlo.dev/docs/guides/load-testing/). # Run a collection Source: https://kurlo.dev/docs/guides/collection-runner/start/ ## Opening the runner Open it from: - Click a collection name in the sidebar to open its overview, then click **Run**. - From a folder's **⋯** menu, choose **Run folder**. - The play icon in the activity rail on the left. - From the workspace overview, choose **Start → Run collection**. Kurlo opens the runner workspace and selects runnable requests from the current collection. Realtime sessions (`SSE`, WebSocket, Socket.IO) are skipped because they do not naturally finish. HTTP, GraphQL, and gRPC requests can run. ## Selecting requests The runner list groups requests by folder and shows each request's method/transport, name, URL and tags. You can: - Select/deselect individual requests. - Select all or deselect all. - Filter with **Only requests tagged** and **Skip requests tagged**. - Run just a folder by launching from that folder's menu. Tags are inferred from folder path, transport label, and request type. For example, `Billing / Refunds / POST / http` gives you useful filters without adding a separate tagging UI. # Timing and iterations Source: https://kurlo.dev/docs/guides/collection-runner/execution/ ## Timing and parallelism The header sums up the run before you start it: selected requests, iterations, the total number of calls and the order. Use **Delay between requests** when a server rate-limits or when order matters. Sequential runs wait between each request. Parallel runs execute one iteration at a time and wait between iterations. Choose **In parallel** under **Order & pacing** only for independent requests. If a test mutates shared environment values, keep the run sequential so each request sees the latest values from the previous request. **Max concurrent requests** caps how many run at the same time (default 8, maximum 64). Raise it for fast, independent read-only endpoints; lower it when the server rate-limits or when a large collection would otherwise open more sockets than the machine is happy with. ## Iterations Set **Iterations** to run the selected set multiple times. Each request gets a result row per iteration, so flaky endpoints are easier to spot. Iterations are ignored when a data file is loaded; the number of rows in the file becomes the iteration count. # Data-driven runs Source: https://kurlo.dev/docs/guides/collection-runner/data/ The runner accepts CSV or JSON files. Each row becomes a set of variables for that iteration and overrides the active environment for the request being sent. CSV: ```csv userId,region 1001,eu 1002,us ``` JSON: ```json [ { "userId": "1001", "region": "eu" }, { "userId": "1002", "region": "us" } ] ``` Inside a request, use `{{userId}}` or `{{region}}` like any other variable. # Rules and reports Source: https://kurlo.dev/docs/guides/collection-runner/reports/ ## Pass and fail rules A request passes when: - The transport succeeds. - The response status is below 400 for HTTP/GraphQL. - gRPC returns `OK`. - All test-script assertions pass. A request fails when the transport errors, headers are invalid, a script errors, a status is considered failed, or any test assertion fails. ## Reports After a run, click **Download report** to save an HTML report. It includes: - Summary counts. - Duration. - Delay/parallel/filter/data-file settings. - Every request result. - Test names and failures. Reports are local files; Kurlo does not upload them anywhere. ## Last run Kurlo remembers the most recent finished run of each collection — every request's status, time, checks and error, up to 500 results. Open the runner on that collection, or switch its *Collection* picker back to it, and the results are there with *Last run* and when it happened above them, until you run again. The collection's own page shows the same run as one line — *Last run 2 hours ago · 12 of 13 passed* — and the link opens the runner. The request list and the results are one continuous list each, however many requests the collection has: scroll through them, there are no pages. After a run, **Failed** above the results narrows the list to the requests that failed or errored, with their failed checks; **All** shows everything again. A run where every request was skipped is not recorded. The results live in the encrypted local profile next to your history, never in the workspace YAML, so they are not committed to Git and stay on this device. ## Common gotchas - **No runnable requests:** the selected collection only contains realtime requests or empty folders. - **gRPC request fails immediately:** select a gRPC method before running it. - **Environment values changed:** scripts can call `pm.environment.set`; after the run Kurlo merges the final environment state back into the active environment. - **Cookies changed:** the cookie jar is refreshed after the run, just like after normal sends. # Response examples Source: https://kurlo.dev/docs/guides/examples/ > Save a response with its originating request and reuse it in mock server routes. An **example** is a response Kurlo keeps: the status, headers and body that came back, paired with a snapshot of the request that produced them. It answers the question a README never quite does — *what does this endpoint actually return?* — and it does it with a recording rather than a description that drifted two releases ago. Examples are not a cloud feature. Each one is a file in your workspace, so a change to an example is a diff someone can review, and a response that quietly changed shape shows up in a pull request instead of in production. # Save a response example Source: https://kurlo.dev/docs/guides/examples/capture/ ## Saving an example Send a request, then in the response panel use **Save as example**. The name defaults to the status code; rename it to what the case actually is — `Empty list`, `Expired token`, `422 missing name`. You can also save one from [request history](https://kurlo.dev/docs/guides/history/): open a row's ••• menu and pick **Save as example**. This is the usual way to capture a failure you have already stopped being able to reproduce. The request's **Examples** tab lists everything saved against it. From there you can rename, reorder, edit the status and body by hand, or delete. Each example records the request it came from and the **match** template Kurlo derived from that URL — `/orders/8123` captured as `/orders/:id`. That template is what the [mock server](https://kurlo.dev/docs/guides/mock-server/) routes on. ## Secrets are redacted on capture A response body is the single most likely place for a token to end up in a commit, so capture redacts in three passes: 1. **Exact values.** Anything held by an environment variable you marked *secret* is replaced with `[secret]`, wherever it appears — including inside a `Location` URL or a message string, where a key-based rule would never look. 2. **A key sweep.** The same rule the export paths use blanks values under credential-shaped keys: `authorization`, `token`, `access_token`, `api_key`, `password`, `set-cookie`, and their relatives. 3. **A warning.** Anything credential-shaped that survived both passes is flagged when the example is saved, so you can look before it reaches a commit. A body with nothing to redact is stored byte for byte. Kurlo does not reformat it: an id larger than JavaScript's safe integer range would come back a different number if it were reserialized, and an example that silently changed its own data would be worse than no example. # Example storage and imports Source: https://kurlo.dev/docs/guides/examples/storage/ ## Where examples live In a [Git-backed workspace](https://kurlo.dev/docs/guides/git-workspaces/), each example is one YAML file under `collections//examples//`, with the response body inside it: ``` collections/ petstore/ examples/ list-pets/ two-pets.yml ``` A multi-line body is written as a YAML block, so a JSON body still diffs line by line, and one file per example means a commit can never carry an example without its body. See the [Kurlo YAML format](https://kurlo.dev/docs/reference/kurlo-yaml-format/) for the field-by-field reference. Kurlo reads every example when a workspace opens, so a broken example file is reported right away, but it hands an example to the editor only when you open its request or export the collection. The mock server lists routes from their method, path and status alone and reads the responses from disk when it starts. A workspace with thousands of imported examples therefore opens about as fast as one without them; the **Examples** tab shows the flying Kurlo bird for the moment it takes the first time. ## Examples arrive with your imports Every import path that carries responses brings them in as examples: | Source | What arrives | |--------|--------------| | Postman | `item.response[]`, both directions — Kurlo exports them too | | HAR | A HAR file *is* a recording of request/response pairs; both halves are imported | | OpenAPI / Swagger | Declared `responses`, including a body derived from the response schema when the spec gives no example | | OpenCollection / Bruno | Saved responses | See [Import & export](https://kurlo.dev/docs/guides/import-export/). # Use a saved example Source: https://kurlo.dev/docs/guides/examples/use/ ## Comparing a response against an example The response panel's **Diff** tab can use a saved example as its baseline instead of the previous response. This is what stops an example from quietly going stale: an endpoint that no longer matches the contract shows up as a diff rather than passing unnoticed. The baseline is chosen per request, and falls back to the previous response if the example it pointed at is deleted. See [Response viewer](https://kurlo.dev/docs/guides/response-viewer/). ## Examples suggest body keys While you write a JSON body, Kurlo offers the next key from the bodies of the request's examples in faded text; `Tab` accepts it. See [Suggestions while you type](https://kurlo.dev/docs/guides/request-types/http/#suggestions-while-you-type). ## Examples feed the mock server Once a collection has examples, Kurlo can serve them over HTTP — path templates, status codes, headers and bodies, exactly as captured. That is the [mock server](https://kurlo.dev/docs/guides/mock-server/), and it needs no extra configuration: an example is already a route. A captured URL is stored as a path template, so `/orders/8123` is recorded as `/orders/:id` and the mock answers for any id. You can edit that template on the example if the guess was wrong. # Mock server Source: https://kurlo.dev/docs/guides/mock-server/ > Serve a collection's saved examples over HTTP on a local port, so a client can be built against an endpoint that does not exist yet. Kurlo can serve a collection's [saved examples](https://kurlo.dev/docs/guides/examples/) as a real HTTP server on your own machine. A front end can then be written against an endpoint the backend has not shipped, and against the failure cases a staging environment will not produce on demand — a 500, an expired token, an empty list. It needs no account and no configuration. An example already records a status, headers, a body and the path that produced them, so it is already a route. # Start the mock server Source: https://kurlo.dev/docs/guides/mock-server/start/ ## Starting it Open the **Mock** tab from the server icon in the activity rail on the left, pick a collection, and press **Start server** at the top right. The status bar beside it shows whether the server runs and its base URL; click the URL to copy it. **Close tab** (`Cmd+W`, or `Ctrl+W` on Windows and Linux) closes the Mock tab like any other tab; a running server keeps running: ``` http://127.0.0.1:3100 ``` Point your client at that instead of the real API and every request matching an example gets the recorded response back. The **Start** button stays disabled until the selected collection has at least one example — there would be nothing to serve. # Match requests to examples Source: https://kurlo.dev/docs/guides/mock-server/matching/ ## What it serves Each example becomes one route, matched on **method** plus the example's **path template**: | Example captured from | Route | |-----------------------|-------| | `GET https://api.example.com/pets` | `GET /pets` | | `GET https://api.example.com/pets/8123` | `GET /pets/:id` | | `POST https://api.example.com/pets` | `POST /pets` | A literal segment beats a parameter, so `/pets/featured` wins over `/pets/:id` regardless of which example was captured first. OpenAPI-style `{petId}` segments match the same way `:petId` does. ### Several examples for one endpoint An example that recorded **query parameters** only answers requests that carry them. That is how one endpoint serves its empty, its full and its error case: | Example | Answers | |---------|---------| | `GET /pets` | any request to `/pets` | | `GET /pets` with `status=archived` | only `/pets?status=archived` | When two examples would answer the same request, only the first can ever reply. Kurlo flags this: the **Routes** header counts the examples that are never reached, and each of them names the example that answers first. Routes are grouped by request. Give them different paths or query values to make the rest reachable. # Inspect requests and edit examples Source: https://kurlo.dev/docs/guides/mock-server/debug/ ## The request log Everything that reaches the mock is listed live — method, path, the status that went back, and which example answered. The **unmatched** rows are the useful ones. They are the difference between *my client is asking for the wrong thing* and *no example covers this yet*, and a request that matches nothing gets a 404 whose body names the routes that do exist: ```json { "error": "No saved example matches this request.", "method": "GET", "path": "/pets/9/toys", "available": ["GET /pets", "GET /pets/:id", "POST /pets"] } ``` The log is kept on Kurlo's side as well as streamed to the panel, so closing and reopening the tab does not lose what arrived while you were elsewhere. A request the client abandoned — it gave up during a reproduced delay — is listed too, with the example that would have answered, rather than vanishing. ## Editing an example while the server runs The mock reloads itself when you change an example it is serving, so it cannot answer with something you already edited. This happens whether or not the mock panel is open — editing an example from the request editor is enough. The routes are swapped on the running server rather than restarting it: the port never moves, open connections are not dropped, and the request log survives, because from the client's point of view nothing happened. A rename does not bounce the server either, because it changes nothing a client can observe. Clicking a route, or a matched row in the log, opens the example behind it. ## Reproducing recorded response times Each example knows how long the real call took. **Reproduce recorded response times** replays that delay, which is a cheap way to see a loading state that a local mock otherwise never shows. It is off by default. # Mock server scope and limits Source: https://kurlo.dev/docs/guides/mock-server/limits/ ## Scope and safety - **Loopback only.** The server binds `127.0.0.1`, never `0.0.0.0`. A mock built from real recorded responses — which may still hold data from a live system — is not something to put on the network by accident. - **CORS is answered for pages served from this machine** — any `localhost`, `127.0.0.1` or `::1` origin on any port — because the first client to hit a mock is usually a browser app running on another port. A page served from anywhere else gets a `403` and no CORS headers: the mock replays responses recorded from real APIs, and a site you happen to have open should not be able to read them. The refusal is listed in the request log with the origin that was turned away. - **One server at a time.** Starting it for a different collection switches it over; the panel says so before you do. - **It stops when Kurlo quits.** There is no background daemon. If the port is taken, Kurlo says so rather than failing silently — pick another one in the panel. ## What it does not do - It does not fall through to the real API for unmatched requests. - It does not template responses: what was captured is what is served, byte for byte. - It does not serve HTTPS, and it does not match on the request body. If you need any of those, [open an issue](https://github.com/stormhop/kurlo/issues) — they are all extensions of the same matching, not rewrites of it. # CLI runner (run & load) Source: https://kurlo.dev/docs/guides/cli-runner/ > Run requests, test scripts and k6 load tests from a Kurlo YAML workspace in the terminal or CI. `kurlo run` executes a [Git-backed YAML workspace](https://kurlo.dev/docs/guides/git-workspaces/) from the command line — the same requests and JavaScript test scripts you run in the app, without the window. It's built for CI: a non-zero exit code fails the build when a request errors or an assertion fails. # Install the CLI Source: https://kurlo.dev/docs/guides/cli-runner/install/ ## Install On a CI runner or any machine with Node.js 18 or later, use the npm package. It has prebuilt binaries for macOS, Linux and Windows on x64 and arm64, and needs no desktop app: ```bash npx -y @kurlo/cli run ./my-workspace --env CI ``` or install it once and call `kurlo` directly: ```bash npm install -g @kurlo/cli kurlo run ./my-workspace --env CI ``` The desktop app is the CLI as well. If it is installed, `/Applications/Kurlo.app/Contents/MacOS/kurlo run` on macOS, or the `kurlo` executable on Linux and Windows, works the same way. ### `EACCES: permission denied` on `npm install -g` npm could not write to the folder that holds global packages. It happens with Node from the nodejs.org installer, which puts that folder in `/usr/local`, owned by the system. It is not specific to Kurlo, and any global package fails the same way. Either skip the install and run the CLI with `npx -y @kurlo/cli`, or move global packages into your home folder once: ```bash mkdir -p ~/.npm-global && npm config set prefix ~/.npm-global echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc npm install -g @kurlo/cli ``` Node installed with Homebrew, Volta or nvm keeps global packages in your home folder already. Avoid `sudo npm install -g`: it works, but leaves root-owned files that break later installs. # Run a collection with kurlo run Source: https://kurlo.dev/docs/guides/cli-runner/run/ ## Quick start ```bash kurlo run ./my-workspace --env Staging ``` ``` ✓ GET https://api.example.com/health → 200 42ms [2/2 tests] ✓ POST https://api.example.com/login → 200 88ms [1/1 tests] 2 requests, 2 passed, 0 failed · 3/3 assertions · 131ms ``` The first argument is the workspace directory (the folder that contains `kurlo.yml`); it defaults to the current directory, so inside a workspace you can just run `kurlo run --env Staging`. ## What it runs - **HTTP and GraphQL requests**, in the order they load from the workspace. - **Pre-request and test scripts** — the same sandboxed JavaScript `pm.*` API as the app. Assertions become the pass/fail signal. - **Collection defaults** — a collection's auth, headers, scripts, and settings are applied exactly as they are in the app, so a request set to **Inherit auth** authenticates in CI too. - **Variable chaining**: a value a test writes with `pm.environment.set(...)` is visible to later requests in the same run, so a login step can hand a token to the requests after it. - **Browser checks**: a request with [browser emulation](https://kurlo.dev/docs/guides/browser-security/) turned on, by itself or through its collection, is sent the way the browser would send it, and a CORS or CSP refusal fails the run. Keep it on for the requests your frontend makes, and CI catches a CORS change before the frontend ships. A request can keep both JavaScript and Tengo scripts. `kurlo run` runs the JavaScript fields when either is present; the app runs the engine selected in **Settings → General → Script engine**, because the workspace file does not record that choice. `kurlo run` skips SSE, WebSocket, Socket.IO, gRPC, MCP, and AI requests. Use the [desktop Collection Runner](https://kurlo.dev/docs/guides/collection-runner/) for gRPC. A request whose pre-request script calls `pm.execution.skipRequest()` is reported as skipped and does not fail the run. Scripts get the same sandbox as the app, including [`pm.crypto` and `CryptoJS`](https://kurlo.dev/docs/reference/scripting-api/crypto/) for request signing. Two capabilities are opt-in because they change what a run can do: - `pm.sendRequest` needs `--allow-send-request`. Without it, a script that calls it fails, which keeps a CI run from making unannounced HTTP calls. - Scripts are capped at 2000 ms; raise it with `--script-timeout` when a heavy assertion suite or signing step needs longer. # OAuth 2.0 in CI Source: https://kurlo.dev/docs/guides/cli-runner/oauth/ A run gets its own access token rather than relying on one the app saved. The saved token lives in the machine-local secret store and never reaches a checkout, so relying on it would mean an OAuth-protected collection simply could not run in CI. Which grants a run can complete on its own: | Grant | In a run | |-------|----------| | Client Credentials | Fetched from the token endpoint. | | Password | Fetched from the token endpoint with the configured credentials. | | Authorization Code / Device Code | Both need a person at a browser. A run swaps the stored **refresh token** instead, which is how these grants are meant to be renewed unattended. | All the requests in a run that share one configuration authenticate once — fifty requests do not mean fifty round trips to the token endpoint. When a grant needs a browser and there is no refresh token to fall back on, the run stops on that request and says so, rather than sending it unauthenticated and reporting a 401 you then have to diagnose. Keep the client secret out of the workspace and pass it in: ```bash kurlo run . --env CI --var oauthClientSecret="$OAUTH_CLIENT_SECRET" ``` # Variables and data files Source: https://kurlo.dev/docs/guides/cli-runner/data/ ## Variables Variables resolve exactly as they do in the app, in ascending priority: 1. **Globals** (`--globals `, `--global-var KEY=VALUE`). 2. **Collection variables** (collection defaults). 3. **The selected environment**, chosen with `--env `. 4. **`--env-file`** — a `KEY=VALUE` file. 5. **`--var KEY=VALUE`** — repeatable, highest priority. The full set of dynamic variables (`{{$guid}}`, `{{$timestamp}}`, `{{$randomEmail}}`, and the rest — see [Environments & variables](https://kurlo.dev/docs/guides/environments/dynamic-variables/)) is generated per use, identical to the desktop app. Environment names are resolved in each collection's own workspace, so two workspaces in one store can both have a `Local` or `CI` environment. A variable marked secret is shown as `[secret]` in the terminal and JSON report, including when it appears in the request URL; a request header marked secret is masked the same way in test errors and script output. Secrets are the reason `--var` and `--env-file` exist: keep them out of the committed workspace and inject them from the CI environment. A value from `--var` or `--env-file` whose name contains `token`, `secret`, `password`, `passwd`, `apikey`, `privatekey`, `credential`, `sessionid`, `cookie`, `authorization`, `bearer` or `jwt` (ignoring case, `-`, `_` and `.`) is masked as `[secret]` in the terminal, the JSON and JUnit reports and script logs. Other values, such as `baseUrl`, are printed as they are. ```bash kurlo run . --env CI --var authToken="$API_TOKEN" --env-file .ci.env ``` ## Data-driven runs Point `--data` at a CSV or JSON file to run the selected requests once per row. Each row's columns become variables for that iteration, and the row is also readable in scripts as `pm.iterationData.get("column")` — the same as Postman/Newman. ```bash kurlo run . --env CI --data users.csv ``` ``` users.csv ───────── name,role ada,admin grace,engineer ``` A request URL like `{{baseUrl}}/users?name={{name}}` runs three times (one per row), each with its own `name`. Values a test writes with `pm.environment.set` still carry forward between requests; the data row is a read-only overlay on top. `--iterations` is ignored when `--data` is set — the row count is the iteration count. JSON data files accept an array of objects, or an object wrapping the rows under `data`/`rows`. # Reports and exported variables Source: https://kurlo.dev/docs/guides/cli-runner/reports/ ## Reporters Run one or more reporters with `--reporters` (comma-separated). Each can go to stdout or a file: | Reporter | Use | File flag | |----------|-----|-----------| | `cli` *(default)* | Human-readable lines, a summary, and a failure list, for the terminal. | — (stdout) | | `json` | A machine-readable summary and per-request results. | `--reporter-json-export ` | | `junit` | A JUnit XML testsuite, for CI test-report UIs. | `--reporter-junit-export ` | ```bash # CLI summary on screen, JSON and JUnit written to files kurlo run . --env CI --reporters cli,json,junit \ --reporter-json-export report.json \ --reporter-junit-export report.xml ``` `--reporter ` is a shorthand for a single reporter. Naming an export file implies its reporter, so `--reporter-junit-export report.xml` alone is enough. ## Exporting variables Write the final variable state (including whatever tests set during the run) to a Postman-compatible file: ```bash kurlo run . --env CI --export-environment final-env.json --export-globals final-globals.json ``` The exported file reads back through `--env-file` or `--globals`, and imports into Postman. # Flags and exit codes Source: https://kurlo.dev/docs/guides/cli-runner/options/ ## Selecting what to run ```bash kurlo run . --env CI --collection "Billing" # one collection, by name kurlo run . --env CI --folder "Billing/Refunds" # a folder subtree ``` ## All flags | Flag | Meaning | |------|---------| | `--workspace ` | Workspace directory (or pass it as the first positional argument). | | `--env ` | Environment to resolve variables from. | | `--collection ` | Only run requests in this collection. | | `--folder ` | Only run requests under this folder path. | | `--data ` | CSV or JSON data file; each row is one iteration. | | `--var KEY=VALUE` | Override a variable (repeatable). | | `--env-file ` | `KEY=VALUE` file or Postman environment JSON that overrides environment variables. | | `--globals ` | `KEY=VALUE` or JSON file of global variables. | | `--global-var KEY=VALUE` | Set a global variable (repeatable). | | `--reporters ` | Comma-separated: `cli`, `json`, `junit`. | | `--reporter ` | Shorthand for a single reporter. | | `--reporter-json-export ` | Write the JSON report to a file. | | `--reporter-junit-export ` | Write the JUnit report to a file. | | `--export-environment ` | Write final environment variables after the run. | | `--export-globals ` | Write final global variables after the run. | | `--timeout ` | Per-request timeout, overriding request settings. | | `--script-timeout ` | Per-script execution timeout (default `2000`, max `60000`). | | `--allow-send-request` | Allow `pm.sendRequest` to make HTTP calls from scripts. | | `--delay ` | Delay between requests. | | `--iterations ` | Run the selected set `n` times (ignored with `--data`). | | `--fail-fast`, `--bail` | Stop at the first failing request. | | `--insecure`, `-k` | Disable TLS certificate verification for every request. | | `--verbose` | Print request/response detail and script output for each request. | ## Exit codes | Code | Meaning | |------|---------| | `0` | Every request succeeded and every assertion passed. | | `1` | At least one request errored or one assertion failed. | | `2` | Setup problem — workspace not found, unknown environment, or no requests matched. | # GitHub Actions Source: https://kurlo.dev/docs/guides/cli-runner/ci/ ## Example: GitHub Actions ```yaml - name: API smoke tests run: npx -y @kurlo/cli run ./workspace --env CI --reporter junit --var token="${{ secrets.API_TOKEN }}" > results.xml ``` ## Related - [Collection Runner](https://kurlo.dev/docs/guides/collection-runner/) — the same idea inside the app, with a data file and parallelism. - [Git-backed workspaces](https://kurlo.dev/docs/guides/git-workspaces/) — the YAML format `kurlo run` reads. - [Scripting API](https://kurlo.dev/docs/reference/scripting-api/) — the `pm.*` API your test scripts use. # Load tests with k6 Source: https://kurlo.dev/docs/guides/cli-runner/load/ Build the flow and load profile in the app with [load testing with k6](https://kurlo.dev/docs/guides/load-testing/). `kurlo load` reads the load tests saved in a collection's `loadtests/` folder. It uses the same flow, collection defaults, auth, data, load profile and thresholds as the app. k6 runs the generated script as a separate process; install Grafana k6 on the machine that runs the test. Listing and exporting work without k6. ```bash kurlo load list --workspace ./api kurlo load export "API smoke" --workspace ./api -o smoke.k6.js kurlo load export "API smoke" --workspace ./api --dir ./k6-export kurlo load run "API smoke" --workspace ./api --env CI --env-file ./ci.env --json summary.json --report report.html ``` The workspace defaults to the current directory. A test can be selected by its name, ID or YAML path, either absolute or relative to the workspace. Names are case-insensitive. If a name appears more than once, use `--collection NAME`, the unique test ID or its YAML path. `list` prints the collection, test name, ID and path; `--collection` also accepts a collection ID. ## Export Without `-o` or `--dir`, `export` writes a self-contained script to stdout. Warnings about request scripts, unsupported auth or request bodies go to stderr, so redirecting stdout produces a clean script. CSV/JSON test data is included in a single-script export. `--dir` creates a new folder with `script.k6.js` and a separate `data.json` when the test uses data. An existing export folder is preserved; choose a new path for another export. ```bash kurlo load export "API smoke" --workspace ./api > smoke.k6.js k6 run smoke.k6.js ``` Request scripts are not translated into k6 checks. Review the warnings and add the checks and extracted values to your load-test flow. ## Environments and secrets The environment saved in the load test is the default. `--env NAME` overrides it and selects an environment in the collection's workspace. Variables resolve in this order, with later values taking precedence: 1. `--globals FILE` and repeated `--global-var KEY=VALUE` supply global defaults. 2. Collection defaults, then enabled values in the selected environment. 3. Process environment values for declared variables. 4. `--env-file FILE`, then repeated `--var KEY=VALUE` overrides. `--env-file` accepts a KEY=VALUE file or JSON, like `kurlo run`. Its values and process overrides stay external in exports, as do saved variables marked secret. k6 reads them from `__ENV`. `run` passes the selected values through the process environment, never through command-line arguments. The machine-local encrypted secret store is not read by the CLI; provide CI secrets through environment variables or an env file. Test-data paths are relative to the workspace root. Use `--inline-secrets` with `export` only when you want secret values written into the exported script. Do not commit or share that file. `run` never writes secret variables into its temporary script, and masks their values in the k6 log. ## Run, reports and exit codes `run` finds k6 on PATH, or uses `--k6 PATH`. It prints the target hosts and starts immediately, so it works in non-interactive CI. k6 output and progress go to stderr; stdout shows the status, totals and a table of thresholds with their actual values. The CLI does not replace the app's last-run result. `--json FILE` saves the raw k6 summary. `--report FILE` saves k6's dashboard HTML report. Both are saved after a threshold failure too. Output files replace existing files; their parent directories must already exist. Very short tests may not produce an HTML report: use a run long enough for the k6 dashboard to collect samples. A requested report that k6 did not produce is reported as an error. Ctrl+C or SIGTERM asks k6 to stop. On macOS and Linux it gets SIGINT, with a forced stop after ten seconds if needed. On Windows the process is killed. The requested summary is saved if k6 produced one; temporary run files are removed afterwards. | Exit code | Meaning | | --- | --- | | `0` | Passed, or list/export/help completed | | `99` | k6 thresholds failed | | `1` | Workspace, validation, export, k6 or artifact error | | `2` | Invalid command or flags | | `130` | Interrupted run | A run that already completed successfully or failed its thresholds keeps its completed exit code even if a stop arrives at the end. Use `kurlo load list --help`, `export --help` or `run --help` for all flags. # Check OpenAPI drift Source: https://kurlo.dev/docs/guides/cli-runner/openapi/ ## Contract drift with kurlo openapi check `kurlo openapi check` tells CI when the API's spec has moved on since a collection was last synced with it. It reads the collection's [OpenAPI source](https://kurlo.dev/docs/guides/openapi-sync/), downloads the current spec and compares it with `openapi/spec.json`, the spec of the last sync applied in Kurlo and committed next to `collection.yml`. It changes no files: apply the changes in the app and commit them. ```bash kurlo openapi check "Pets API" --workspace ./api kurlo openapi check --workspace ./api --env CI --var specToken="$SPEC_TOKEN" kurlo openapi check "Pets API" --workspace ./api --spec ./build/openapi.json --reporter json ``` The output lists operations new in the spec, changed (parameters, request body, responses, security or description, with `$ref`s followed), moved to another path under the same `operationId`, and removed, plus a change of servers. It also names requests in the collection that are not linked to any operation. `x-` extensions are ignored. | Flag | Meaning | |------|---------| | `[collection]`, `--collection ` | Collection to check. Optional when only one collection is synced. | | `--workspace ` | Workspace directory (default `.`). | | `--spec ` | Compare with this file, for example one your build generated, instead of the collection's source. | | `--env `, `--env-file `, `--var KEY=VALUE` | Values for `{{variables}}` in the source URL and its headers. Collection variables are used too. | | `--reporter cli\|json` | Text (default) or a JSON report. | | `--insecure` | Skip TLS certificate verification when downloading the spec. | | Exit code | Meaning | | --- | --- | | `0` | The spec matches the last sync. | | `1` | The spec changed. | | `2` | The check could not run: no such collection, no sync applied yet, an unset variable, or the spec could not be downloaded or read. | # Load testing with k6 Source: https://kurlo.dev/docs/guides/load-testing/ > Build a load-test flow from a collection, choose the load and pass criteria, and export or run it with local Grafana k6. Load tests turn requests from a collection into a repeatable flow for [Grafana k6](https://grafana.com/docs/k6/). Kurlo edits the flow, generates the script and shows the last result. Your installed k6 generates the traffic. You can export a script without installing k6. Use the [Collection Runner](https://kurlo.dev/docs/guides/collection-runner/) to execute requests and their test scripts as functional checks. Use a load test to repeat a flow with virtual users or a target iteration rate and judge its response times, errors and checks against thresholds. # Create your first test Source: https://kurlo.dev/docs/guides/load-testing/start/ 1. Save an HTTP or GraphQL request in a collection. 2. Open its menu and choose **Load test this request**. Kurlo opens a one-step **Smoke** test named *New load test*: two virtual users for one minute. **New load test** in the collection menu starts the flow with every HTTP and GraphQL request in the collection instead, and **New load test from folder** in a folder menu with the requests in that folder and its subfolders; remove the ones you do not need. If the flow is empty, it lists the collection's requests: tick them in the order they should run — each shows its position — or use **Select all**, then click **Add requests to the flow**. 3. Give the test a name and choose its environment. **Active environment** follows the workspace's current selection; choosing a named environment stores that choice with the test. 4. Review **Flow**, **Load & thresholds** and **Data & options**. The **Plan** line under the name sums up the test — steps, peak load, total duration, pass criteria and test data — and each item opens the tab that sets it. When something needs fixing, the field is marked where it is and its tab gets a red dot. 5. Click **Save**. A new test is an **Unsaved draft** — even with autosave on, it reaches the collection and the sidebar only when you save it. The open test has its own tab at the top, so you can switch to requests and come back without losing edits; closing the tab, or opening another load test, asks whether to save a draft you have changed or unsaved changes. A draft you have not touched since it opened closes without asking. Once saved, later edits follow your autosave setting. Saved tests are listed in a collapsible **Load tests** group at the end of their collection; its **+** button starts another test. 6. Choose **Export k6 script**, or install k6 and click **Run with k6**. A test has one flow. Its steps can use saved HTTP and GraphQL requests from the same collection. Requests remain linked to the collection, so changes to a request are picked up by the next export or run. The collection's defaults, headers, auth and environment variables feed the generated script. # Build a flow Source: https://kurlo.dev/docs/guides/load-testing/flow/ Each virtual user, or **VU**, runs the steps from top to bottom. One pass through the flow is an **iteration**. Steps that run once per user are grouped under **Setup**, the rest under **Every iteration**. Each step shows the values it saves, the saved values it uses from earlier steps, its checks and its wait. Add a request with **+ Add request from collection**, click a step to edit its settings, and use the move buttons that appear on the selected or hovered step to change the order. To replace its request, use the **Replace request** button beside the move and remove buttons. Replacing a request keeps the step’s checks, saved values and waits. The compact name field and **Save** / **Revert unsaved changes** controls above the flow work like those on saved requests. Revert restores the whole test to its saved state. Use the load test’s sidebar menu to **Run with k6**, **Export k6 script**, **Rename**, **Duplicate** or **Delete** it; **Run with k6** there runs the saved version. A dot beside the name shows the last result: green for passed, red for failed, amber for stopped, and a pulsing blue dot while it runs; double-click its sidebar name to rename it inline. **Open request** opens the linked request itself. ## Run once per user Steps normally run on **Every iteration**. Choose **Once per user** for setup that each VU should do only once, such as logging in. Each VU has its own saved values; a token extracted by one user is not shared with the others. ## Save values from a response In **Save from response**, click **+ Save a value**, name the variable and choose its source: | Source | Path example | Saved value | | --- | --- | --- | | JSON path | `$.access_token` | The response's `access_token` field | | JSON path | `$.items[0].id` | The first item's `id` | | JSON path | `$['x-request-id']` | A field whose name needs brackets | | Header | `X-Request-Id` | The response header value | | Regex | `orderId=(\w+)` | The first capture group | Use simple property paths and array indices for JSON extraction; JSONPath filters, recursive searches and wildcards are not supported. Variable names can contain letters, digits and underscores, must not start with a digit, and must be unique across extraction rules in the flow. For a login → orders flow: 1. Save a **Login** request whose JSON body uses `{{email}}` and `{{password}}`. 2. Add it as the first step, choose **Once per user**, and save `token` from JSON path `$.access_token`. 3. Set the **List orders** request's bearer token to `{{token}}` and add it as the next step. Variable lookup starts with extracted values, then checks the current data row, the request’s **Pre Request Vars**, the chosen environment, and collection/global defaults. If a row omits a field, the request can still use its default. A value saved by a step becomes available to subsequent steps and later iterations of that VU. ## Check responses Click **+ Add check** to check the status, the presence of a JSON field, or whether the body contains text. For example, check **Status is** `200` on Login and **JSON field exists** `$.items` on List orders. A failed check lowers the **Checks passed** rate; it does not stop the flow or make the run fail by itself. Add a threshold for **Checks passed** when those checks should decide whether the run passes. ## Wait between requests **Wait after this step** is a minimum delay. **Random extra wait** adds a random amount on top. A wait of `500ms` plus up to `1s` pauses for between half a second and one and a half seconds. For a once-per-user step, the wait happens only when that step runs. # Choose the load Source: https://kurlo.dev/docs/guides/load-testing/profiles/ Open **Load & thresholds**. Set **Normal load** and pick a preset — each card shows the shape it applies — then adjust its duration or stages. The test stores only the resulting load, not the preset's name: a card stays highlighted while the settings match that preset exactly, and **Custom** is highlighted as soon as you change a value. The chart shows the planned load over time; hovering or editing a stage highlights its part of the chart. Applying a preset replaces the load profile; it keeps your flow, checks, data and thresholds. | Preset | Starting profile | | --- | --- | | Smoke | 2 users for 1 minute | | Load | Ramp to normal load over 2 minutes, hold for 10 minutes, ramp down over 1 minute | | Stress | Four 3-minute stages at 50%, 100%, 150% and 200% of normal load, then a 2-minute ramp down | | Spike | Ramp to 10× normal load over 10 seconds, hold for 1 minute, ramp down over 10 seconds | | Soak | Ramp up over 5 minutes, hold for 2 hours, ramp down over 5 minutes | ## Users or iterations per second **Virtual users** keeps a chosen number of VUs busy. Each user starts its next iteration after finishing the previous one, including waits. Slower responses mean fewer completed iterations per second. **Iterations per second** starts whole flow iterations at the target rate. This is not a request-per-second target: one iteration may send several requests. The **Smoke** preset in this model starts two iterations per second for one minute. Both models support a constant load or stages. Their k6 executors are `constant-vus`, `ramping-vus`, `constant-arrival-rate` and `ramping-arrival-rate`. For arrival-rate tests, set the preallocated users and maximum users high enough to sustain the target rate; k6 may need more users when responses slow down. The preview shows the planned profile, not measured traffic. ## Decide whether a run passes Add thresholds under the load profile. Each reads as a sentence, such as *p(95) Response time of All steps must be < 500 ms*, and applies to **All steps** or one selected step: | Metric | Example | Meaning | | --- | --- | --- | | Response time | `p(95) < 500 ms` | The 95th-percentile request duration stays below 500 ms | | Failed requests | `< 1%` | Fewer than 1% of requests are counted as failed by k6 | | Checks passed | `> 99%` | More than 99% of checks pass | Response-time statistics include median, average, minimum, maximum, p90, p95 and p99. The UI uses milliseconds for durations and percentages for rates. In YAML and k6 scripts, rates use fractions: `1%` becomes `0.01`. A failed threshold makes the run **Failed**, even if the process finishes normally. Enable **Stop the test early** to let k6 stop a run when that threshold fails. A failed check and a failed HTTP request are separate metrics; set thresholds for both when both matter to your test. # Use CSV or JSON data Source: https://kurlo.dev/docs/guides/load-testing/data/ Put a data file inside the workspace folder and open **Data & options**. Click **Choose file…**, or enter a path such as `data/users.csv`. Kurlo stores a path relative to the workspace root and previews the first five rows. ```csv email,name ada@shop.test,Ada grace@shop.test,Grace ``` JSON can be an array of objects: ```json [ { "email": "ada@shop.test", "name": "Ada" }, { "email": "grace@shop.test", "name": "Grace" } ] ``` Each column or object key becomes a variable such as `{{email}}`. Select how rows are assigned: - **One row per user** keeps a row for that VU. Users wrap around when there are more users than rows. This works well with a once-per-user login step. - **Next row each iteration** cycles through rows using the scenario's iteration index across users. - **Random row** chooses a row each iteration; rows can be reused. The same tab has a timeout per request and **Skip TLS certificate checks**. Leave the timeout empty to keep the request's timeout; fill it to override it for the load test. # Export to k6 Source: https://kurlo.dev/docs/guides/load-testing/export/ Click **Export k6 script** to inspect the generated JavaScript and see what carries over. Choose: - **Single script** for one self-contained `.k6.js` file, including test data. - **Folder** for `script.k6.js` and a separate `data.json` when data is configured. **Save folder…** asks for a parent directory and creates a folder named after the test. It preserves any existing export folder. **Pass when running** keeps secret variable values out of the script. Supply them in the environment when running an exported script, for example in a macOS or Linux shell: ```bash password='your-test-password' k6 run checkout-flow.k6.js ``` For a secret defined in a request’s **Pre Request Vars**, use the environment variable name shown for that request in the export dialog. This lets two requests use different secrets with the same variable name. For a folder export, run `k6 run script.k6.js` from that folder. When Kurlo starts k6 itself, it supplies the selected secret variable values through the child process's environment. **Write into the script** includes secret values in the exported file. Do not commit or share that file. Data files are also included in exports, so use test data you intend to share. You can edit the exported JavaScript to add k6 behavior beyond the editor. Changes to the exported script do not update the saved load test. **Run with local k6** in the export dialog runs the current flow through the same launch path as the editor's run button. ## What carries over HTTP and GraphQL requests carry their supported bodies, headers, collection defaults, variables, checks, extractions, waits, load profile and thresholds. Bearer, basic, API key and digest auth are supported. OAuth 2.0 client credentials and password grants can fetch a token once before the flow starts. A saved OAuth token can be exported with a warning that it may expire. Review the export warnings before running: - Pre-request and test scripts are not translated. Add load-test checks and extraction rules for the behavior you need. - OAuth 1.0, AWS signing, interactive OAuth grants without a usable saved token, and client certificates do not carry over as equivalent auth flows. - File uploads and binary bodies are not exported. Text multipart fields are sent URL-encoded, with a warning. - Unknown dynamic variables are left as written with a warning. Supported dynamic variables are generated in the script. The flow picker excludes WebSocket, gRPC, SSE, Socket.IO, MCP and AI requests. A load test runs one sequential flow; parallel flows and batch requests are not part of this editor. # Install and run k6 Source: https://kurlo.dev/docs/guides/load-testing/run/ Kurlo uses an independently installed k6 program. On macOS with Homebrew: ```bash brew install k6 ``` On Windows with Windows Package Manager: ```powershell winget install k6 --source winget ``` For Linux packages, standalone binaries and other installation options, follow the [official k6 installation guide](https://grafana.com/docs/k6/latest/set-up/install-k6/). If Kurlo cannot find k6, it opens an installation dialog. Use **Choose the k6 program…** to select the binary yourself, **Check again** after installation, or **Export script only** to continue without a local runtime. Click **Run with k6**. For targets outside this computer's loopback addresses, Kurlo shows the hosts and asks you to confirm before sending traffic. For a protected environment, type the requested host name. Only one load test can run in the app at a time. ## Watch and stop a run The **Results** tab shows the current stage and what it is doing, elapsed time as a clock such as `0:15 / 1:00` and the approximate time left, the planned load with a marker at the current moment, users, completed and interrupted iterations, and the k6 log, which you can collapse. **Open k6 live dashboard** opens k6's own dashboard while the run is active. **Stop** asks k6 to finish on macOS and Linux; after ten seconds Kurlo kills it if it has not exited. On Windows it is killed immediately. A stopped run keeps the summary when k6 produced one. Its status is **Stopped** unless k6 had already completed and returned its final result. ## Read the result When the run finishes, Kurlo shows **Passed**, **Failed**, **Stopped** or **Did not finish**. The result includes each threshold's actual value with a bar against its limit, total requests and throughput, response times, failed requests, checks and a table per step with a bar for each step's p95. The **Results** tab label also shows the last status. Use **Open HTML report** for k6's exported dashboard report and **Save summary JSON** for the raw k6 summary. The HTML report is available when k6 generated it; very short runs may not collect enough dashboard samples. Kurlo keeps only the last result for each test, on this device. A new run replaces it. The result, summary and HTML report are local app data, not part of the workspace YAML. There is no run history or baseline comparison. # Save, share and run in CI Source: https://kurlo.dev/docs/guides/load-testing/ci/ The load-test definition lives alongside its collection's requests: ```text workspaces//collections//loadtests/.yml ``` Commit that definition and any shared data files with the workspace. Secret variable values belong in environment configuration rather than the test definition. See the [YAML reference](https://kurlo.dev/docs/reference/kurlo-yaml-format/load-test/) for the file format. The headless CLI reads the same tests: ```bash kurlo load list --workspace ./api kurlo load export "Checkout flow" --workspace ./api --dir ./k6-export kurlo load run "Checkout flow" --workspace ./api --env CI --env-file ./ci.env --json summary.json --report report.html ``` The CLI can select a test by name, ID or YAML path. Threshold failures exit with code `99`; runtime errors use `1`, usage errors use `2`, and interrupted runs use `130`. See [CLI load testing](https://kurlo.dev/docs/guides/cli-runner/load/) for variable precedence, all flags and report handling. # Agent mode Source: https://kurlo.dev/docs/guides/agent/ > Run requests, investigate failures, and edit collections with Kurlo's built-in agent or an installed coding agent. The agent works inside Kurlo on the open workspace. Ask it in plain words to run a request, find out why one failed, run a collection and explain the failures, or add a request with tests, and it does the work with Kurlo's own tools: the same ones [`kurlo mcp`](https://kurlo.dev/docs/guides/mcp-server/) gives to Claude Code or Cursor, called directly inside the app. Kurlo's built-in agent uses a model you connect in [Settings → AI](https://kurlo.dev/docs/guides/settings/ai/#ai). You can use OpenRouter, an Anthropic, OpenAI, or compatible API key, or a local model through Ollama or LM Studio. You can also select an [installed coding agent](https://kurlo.dev/docs/guides/agent/local-agents/) and use its existing account. # Open the agent Source: https://kurlo.dev/docs/guides/agent/start/ Click the sparkle icon in the activity bar on the left, or press `Alt Cmd/Ctrl 4`. Until you open it for the first time, the icon carries a small blue dot. The sidebar has **New chat** at the top and your chats below it, newest first under **Today** and **Earlier**; type in **Filter chats** to find one by its name. Each chat is marked with the agent it runs on: the Kurlo bird for the Kurlo agent, the Codex and Claude Code marks for those agents; an amber dot instead of the time means the chat waits for your approval. **New** beside **Chats** starts a new chat. The main area opens the **Agent** tab. When you switch to another tab, such as a request the agent opened, the sidebar goes back to what it showed before, and returns to your chats when you come back to **Agent**. Without a connected model the tab offers four ways to connect one: **Connect OpenRouter** signs you in through the browser, **Your API key** opens the key form, **Local model** looks for Ollama and LM Studio on this computer, and **Codex on this computer** opens the Codex connection in Settings → AI. An empty chat offers four starting tasks, such as **Why did my request fail?** and **Run and check the collection**. Clicking one puts its text in the message box. # Local agents Source: https://kurlo.dev/docs/guides/agent/local-agents/ The agent picker in the message box chooses who answers. **On this computer** lists installed coding agents that run with their own account, such as Codex, with their models. Effort has its own menu beside the picker. **Kurlo agent · any model** lists your model connections, such as OpenRouter or an API key. Both share one chat list. To connect Codex: 1. Open **Settings → AI → Your agents**, or click **Connect** next to Codex in the agent picker. 2. Kurlo checks for Codex CLI. If it is missing, install it with `npm install -g @openai/codex`, then click **Check again**. Use **Choose executable** or enter its full path if Kurlo cannot find it. 3. If Codex is already signed in, click **Use this account**. Otherwise click **Sign in** and complete the official Codex sign-in in your browser. **Reopen browser** opens the same pending sign-in; **Cancel sign-in** stops it. 4. Choose an available model and connect. ChatGPT sign-in uses your plan's available usage; an existing API-key login uses API billing. Choose a Codex model in the agent picker, then use the separate **Effort** menu beside it. It lists the reasoning levels the model supports and highlights the model's default until you choose another. An explicit choice is saved with the chat; choosing the highlighted default again goes back to the CLI's own default on the next turn, including in an existing session. Changing to a model that does not support the chosen effort returns to its default. Codex calls Kurlo's tools through its local app-server connection. Reads run immediately; requests that may change server data and workspace edits use the same approval cards as the Kurlo agent. Shell execution and inherited external integrations are disabled, and Codex runs with a read-only sandbox. The active request editor is not attached automatically. **Stop** cancels the active work and closes its process. The next message resumes the native Codex session. If that session is unavailable, Kurlo shows an error; start a new chat rather than silently losing the conversation. A chat stays with the agent it started on; to switch agent, start a new chat. In a new chat, switching agent keeps what you typed and the chosen collection and environment. **Manage connections** in the agent picker opens the connection settings. **Remove connection** stops active Codex work and removes the connection from Kurlo; it does not sign you out of Codex or delete its native sessions. The CLI manages its own credentials. Kurlo stores the executable path, default model and native session ID, not your subscription tokens. Codex also keeps its own conversation data in its profile, governed by its settings, separately from Kurlo's encrypted chat copy. Removing a chat in Kurlo does not delete that native copy. To connect Claude Code: 1. Open **Settings → AI → Your agents**, or click **Connect** next to Claude Code in the agent picker. 2. Kurlo checks for the Claude Code CLI and shows its version. If it is missing, install it with `npm install -g @anthropic-ai/claude-code`, then click **Check again**. Use **Choose executable** or enter its full path if Kurlo cannot find it. 3. If the CLI is already signed in, its account and plan show under **Signed in** (or **API key** / **Cloud provider**); choose a model and click **Use this account**. Otherwise click **Sign in** and complete the official Claude sign-in in your browser. The card then shows **Connected**. **Reconnect** checks the CLI again (if the CLI has signed out since, the card shows **Signed out** and a **Sign in** button), the model menu changes the default model at once, and **Remove connection** stops active Claude Code work and removes the connection from Kurlo without signing the CLI out. Select **Claude Code** under **On this computer** in the agent picker; its models are listed below it by full name (Fable 5.2, Fable 5.1, Opus 5.5, Sonnet 5.5, Haiku 5.5), and the one the CLI uses by default is preselected and marked **default**. The **Effort** menu beside the picker offers Low, Medium, High, Extra high and Max; High is preselected, and Kurlo always passes the chosen level to the CLI. Some models, such as Fable, may need usage credits on your Claude plan; the CLI's reason then shows in the chat. **Chat details** shows the chat's tokens, the cost at API prices (a subscription is not billed per token), the last request's context against the model's window, and the Claude plan's 5-hour and weekly limits with their reset times; Kurlo reads the limits and the default model with the CLI's `/usage` command, which uses no tokens, whenever it checks the connection, and updates them after each turn; they also appear in Settings → AI. **Stop** ends the current turn, and your next message resumes the same native session. Workspace edits use Kurlo’s approval cards. Claude Code keeps its native conversation separately from Kurlo’s encrypted chat copy. Deleting the chat in Kurlo removes the Kurlo copy. # Ask the agent Source: https://kurlo.dev/docs/guides/agent/chat/ ## Ask Type in the box at the bottom and press `Enter` (`Shift Enter` adds a line). The header shows the chat's name, which you can click to rename. Chips at the left of the message box choose the collection and environment it works on: - **Collection.** The collection to work in unless you name another. **Any collection** leaves it to the agent. - **Environment.** The environment its requests use. A protected environment is listed, but the agent cannot send with it; run those requests yourself. The agent picker at the right of the message box chooses the agent and model. Choose **Claude Code**, **Codex** or a Kurlo agent connection to see its models and a search field. The one marked **default** is the model set in Settings → AI. Picking another model changes it for this chat only: the connection, its default model and AI requests that use **Kurlo connection** stay as they are. `↑` and `↓` move between options, `Enter` picks one and `Escape` closes the menu. The choice applies to your next message and is locked while the agent works. For Codex, a separate **Effort** menu sits beside the model picker. It offers the levels supported by the selected model. New chats keep your effort choice; switching to a model that does not support it uses that model's default. **Templates** in the message box offers ready requests: why the last request failed, run and check the collection, write tests for a request, cover an endpoint, and explain a request. Choosing one puts its text in the box with the part to fill in, such as `REQUEST NAME`, selected; edit it and press `Enter`. Templates your team keeps in [`kurlo-agent.md`](https://kurlo.dev/docs/guides/agent/team-notes/#team-notes-in-kurlo-agentmd) appear above the built-in ones under **From kurlo-agent.md**. The answer streams in as the agent works. The tool calls of a turn sit in one card, one line each, such as **Ran a request** or **Saved a request**, with a check when done, a cross when it failed and a shield while it waits for you; a run also shows the request line, status code and time. Click a line to see the arguments and the result, and click **Open request**, **Open entry** or **Open environment** to jump to what it touched. **Stop** ends the turn, including while the first response or a confirmation is pending. An unanswered confirmation stops the turn after 30 minutes; retry when you are ready. If sending your decision fails, the card keeps its buttons available to try again. Messages and answers can be selected and copied like any text; hovering one also shows a copy button, and **Retry** sends your last message again when a turn failed or stopped before answering. Hover a message you sent to **Edit message**: its text goes back into the box and sending replaces it and everything after it. **Branch from here** instead starts a new chat, named after this one with **(branch)**, that holds the conversation up to that message, so the original chat stays as it was. A long chat initially loads its latest 40 exchanges. Scroll to the top or click **Load earlier messages** to fetch another 40 without losing your reading position. Only messages near the viewport are rendered. Each chat runs on its own: start a task, open another chat or **New**, and send there while the first one keeps working. A pulsing dot in the sidebar marks every chat that is working, and **Stop** in a chat stops only that chat's turn. Codex and Claude Code still run one turn at a time. A saved chat has its name at the top; click it to rename the chat. Archive, export and delete are in the chat's **•••** menu in the sidebar. **Chat details**, the panel button at the right of the status bar, opens a side panel with the chat's collection, environment, agent and effort, token usage and the last request's context size, the files the agent changed or wants to change, its recent runs with their status codes and, for Codex, each plan limit with its reset time. Each part of the panel folds: click its title to open or close it, and a closed part shows a short summary on the right, such as the collection and environment, the budget used or the token count and cost. Kurlo remembers which parts are open. It sits beside the conversation; in a narrow window it takes the conversation's place until you close it with `Escape`, the close button or the status bar button. Kurlo remembers whether the panel is open. # Running requests and tests Source: https://kurlo.dev/docs/guides/agent/requests/ Name a saved request, folder or collection in the chat. The agent can run HTTP, GraphQL, unary gRPC, MCP and AI requests. For an MCP endpoint, ask it to list available tools or call one with specific arguments. HTTP results include timings, redirect hops and the negotiated TLS details when available. For WebSocket, Socket.IO, SSE or streaming gRPC, ask the agent to connect, exchange messages and report what it receives. SSE only receives events. A server-streaming gRPC call sends its saved message when it opens. For client-streaming and bidirectional gRPC, ask the agent to send each message and finish sending when ready. **Stop** and the end of the turn close the connections. For a collection run, name the number of iterations, a delay between requests and whether to stop at the first failure. To use test data, put a CSV or JSON file in the workspace and give the agent its relative path. Each row drives one iteration. The agent reports per-request results, assertions, skips and elapsed time. Ask the agent to save a load test and run it with the installed k6. The run continues in the background. Ask for its progress, summary or a comparison with an earlier run of the same test or another saved test. To serve saved examples, ask it to start a mock for a collection and inspect the request log. The mock stays up until you or the agent stops it. Ask for cookies that apply to a domain to see their names, paths, expiry and flags. Clearing the workspace's jar requires a fresh approval each time. # Project context and limits Source: https://kurlo.dev/docs/guides/agent/context/ ## Project folders, files and imports Use the folder button in the message box to connect a source directory. The connection is saved with the chat when you send a message. The agent can list files, search for text and read lines inside that directory. Project access skips symlinks, hidden configuration and common credential files. Remove the **Project** chip and send a message to disconnect it. Ask the agent to find the routes in the project and sync your collection, or ask it to cover one endpoint such as `POST /pets`. It can use the source to build a request, example and tests. Workspace changes go through the usual approval card. Drop files onto the message box or use **Attach file** to add a specification, proto, CSV, text file or image to the next message. Ask the agent to import an attached OpenAPI file, read a proto or run a collection with attached CSV or JSON data. PNG, JPEG and WebP go to the selected model as images. The agent reads SVG as source text. Attach the file again to use it in another turn. Click a file above a sent message to open it. For images, use **+** or **−** to zoom and **Fit** to return to the initial view. Kurlo keeps an encrypted local copy with the chat so you can open the file after moving or deleting the source. Ask for an import from a file in the connected folder, an attachment, a pasted cURL command or an OpenAPI URL. The agent previews the changes before showing **Apply this import?** with the list of requests it adds or changes. Approve to write the files or reject to leave the workspace as it was. The same Go importers work through the MCP server without a desktop window. [MCP import tools](https://kurlo.dev/docs/guides/mcp-server/tools/#import-requests-and-read-project-source) You can also ask the agent to read or update the Markdown docs of a request or collection, or generate a code snippet for an HTTP or GraphQL request. Give the request name and your language, for example, “Show me the Python snippet for Get pet.” ## Usage, context and limits Below the message box, input and output token counts show usage recorded for this chat. Codex can also report account quota windows and the context window size. Codex stops a turn after five minutes without progress, excluding time spent waiting for your confirmation, and after 50 tool calls. It manages its model context through the CLI and can compact it automatically; Kurlo shows **Compacting context…** while this happens. Compaction changes what the model retains in its working context, while the conversation remains available in Kurlo. Below the message box, **Plan N% left** shows the tightest Codex quota window and turns amber below 30%; click it to open **Chat details**, which lists every window, such as the 5-hour and weekly ones, with a bar and its reset time. Click it to see reset times when available. These are account limits, shared with other Codex sessions, rather than a per-chat token budget. Kurlo updates them from the CLI's account snapshot and live notifications. Missing quota information is hidden. For the Kurlo agent, **Chat details** also shows the cost of the chat when the provider reports it (OpenRouter does) and the context of the last request against the model's window, which Kurlo takes from the provider's model list or assumes to be 128,000 tokens (32,000 for local models). Within one turn, when the conversation would take more than 70% of that window, Kurlo shortens the oldest tool results, keeps the last two in full and tells you how many it shortened; the saved chat keeps everything. With an Anthropic connection the stable start of every request, the instructions, tools and earlier messages, is marked for prompt caching, so later steps of a turn are read from the cache at a lower price. **Budget** in **Chat details** caps a chat, up to 1,000,000,000 tokens and 100,000 requests, by tokens, counted over the whole chat, and by sent requests, counted as every request the agent sends with `run_request`, `send_request`, `run_collection` or `generate_tests`. Leave a field empty for no limit. The agent stops when the chat reaches either one and tells you, and a call that would go over the request budget does not run. Raise the budget to continue. When a Kurlo agent chat gets long, open **Chat details → History** and choose **Compact chat**. Kurlo asks the chat's model for a summary of the conversation so far: what you asked for, what was created or changed, results that matter later and what is still open. From your next message on, the agent works from that summary instead of the earlier messages, so each request is smaller. The messages stay in the chat for you, under a line that marks where the compacted part ends, and **Show summary** shows what the agent sees. Compact again after more messages to fold them into the summary too. Editing or branching from a message inside the compacted part drops the summary. Codex and Claude Code manage their own history and do not offer this. In **Chat details**, **Context (last request)** compares the last reported request's token count with the reported model window. It is a snapshot, not cumulative token usage or a prediction of the next request after compaction. The last reported snapshot is retained with the chat; if the CLI does not report a window, no percentage is invented. # Approvals and permissions Source: https://kurlo.dev/docs/guides/agent/approvals/ ## What it may do without asking **Approvals**, next to the model in the message box, sets how much the Kurlo agent asks in this chat: - **Ask always.** Only reading runs on its own. Every request, even a `GET`, and every change waits for you. - **Ask for changes.** The default, as in the table below. - **Auto.** Requests and changes to the workspace files run on their own. A `POST`, `PUT`, `PATCH` or `DELETE` to a host that is not trusted, a one-off call to a host the workspace does not use, starting k6, clearing cookies, OAuth sign-in and `git push` still wait for you. **Chat details → Permissions → Trusted hosts** lists hosts where `POST`, `PUT`, `PATCH` and `DELETE` run without asking, such as `localhost` or `*.staging.example.com`; new chats start with `localhost` and `127.0.0.1`. Kurlo resolves the request's URL with the chosen environment before it checks the host, and asks when the host contains a variable it cannot resolve. An environment marked as a [sandbox](https://kurlo.dev/docs/guides/environments/secrets/#sandbox-environments-for-the-agent) lets every request sent with it run without asking. The settings are saved with the chat when you send a message. | The agent wants to | What happens | |--------------------|--------------| | List or read requests, environments or history, or diagnose a failure | Runs at once | | Run a request, a collection or a one-off call that only sends `GET`, `HEAD` or `OPTIONS` | Runs at once | | Send a one-off call to a host that no saved request or variable of the workspace uses | Asks first, even for `GET`, unless the host is trusted | | Send any other method, such as `POST` or `DELETE` | Asks first, showing the call | | Run a saved unary gRPC, MCP or AI request, or open a live connection | Asks before contacting the configured server | | Send a live message or start or stop the mock server | Asks first | | Start k6 or clear the cookie jar | Asks every time | | Fetch an OpenAPI URL | Asks before fetching | | Apply an import or edit Markdown docs | Shows the changes for approval | | Check k6 progress, compare results, read the mock log or list cookie metadata | Runs at once | | Change the workspace: save or delete a request, save an example, set a variable, create a collection, write tests or save a load test | Asks first, showing the change file by file | | Read the Git status or diff of the workspace, or build a pull request link | Runs at once | | Create a Git branch or commit workspace files | Asks first; a commit shows the files it includes | | Push the current branch | Asks every time, and only when you asked it to push | Before a task with several changes the agent shows **Follow this plan?** with its steps and, under **Runs without asking again**, the exact calls it intends to make, each with its target such as a request path, a variable or a URL. **Approve plan** lets exactly those calls run without asking for the rest of the turn; a call listed without a target runs once. Anything else still waits for you, and `git push` never joins a plan. An approval card lists what would change in plain terms: each request, environment, collection or the globals, where it lives, such as `Shop API / Orders`, whether it is new, changed or deleted, and which fields change, such as **Tests added** or the old and new URL. Internal details such as ids are left out; a change that touches only them says so. **Show file changes** opens the exact lines of the YAML file. With one or two changes every item is open; with more, the card shows a short count such as **9 new requests** and a folded list you open item by item or with **Expand all**, and the list scrolls inside the card so the buttons stay close. **Apply** writes the changes, **Reject** tells the agent no and it asks what you want instead, and **Allow for this chat** applies this change and lets the same tool run without asking for the rest of the chat. Nothing is written while the card waits, and Kurlo keeps saving your own edits in the meantime. If you change one of those files before you click **Apply**, the change is dropped and the agent is told to try again, so it never overwrites your edit. The agent never writes a secret into the workspace: it uses a `{{variable}}` and asks you to set the value. Secret values reach it only as `[secret]`. # Team notes Source: https://kurlo.dev/docs/guides/agent/team-notes/ ## Team notes in kurlo-agent.md Keep conventions for the agent in `kurlo-agent.md` at the root of the workspace folder: which environment to use for tests, naming rules, tags, what never to touch. The file is plain Markdown and lives in Git with the workspace, so the whole team shares it. The Kurlo agent reads it at the start of every turn and follows it within its [permissions](https://kurlo.dev/docs/guides/agent/approvals/). When the agent learns a convention that is missing, it offers to add it; the change shows as a diff and always waits for your approval, even after **Allow for this chat**. To edit the file in Kurlo, choose **Edit kurlo-agent.md…** at the bottom of **Templates** in the message box, or select **kurlo-agent.md** next to **Team notes** under **Chat details → Context**. When the workspace has no such file yet, the menu reads **Create kurlo-agent.md…** and the editor starts from an example with conventions and one template; **Create file** writes it. **Preview** shows the rendered Markdown, and the bottom line shows the size against the 32 KB limit and how many templates the file has. Press `Cmd+S` (`Ctrl+S` on Windows and Linux) or **Save** to save; closing with unsaved changes asks first. If the file changed on disk after you opened it, for example in another editor or through `git pull`, Kurlo does not overwrite it: **Load newer version** replaces your text with the copy on disk, and **Replace it** saves your text over it. A file over 32 KB is not opened here; shorten it in another editor first. Kurlo treats `kurlo-agent.md` as one of the workspace's files in Git: it shows under Changes on the Git screen, **Commit** includes it, and with **Branch** on, a change the agent makes to it is committed to the agent's branch like any other. Under a `## Templates` heading, each `### Title` with the text below it becomes a template in the message box: ```markdown # Team notes Use the Staging environment for tests and tag smoke requests with `smoke`. ## Templates ### Smoke check Run the Smoke collection against Staging and explain every failure. ``` # MCP servers and Git Source: https://kurlo.dev/docs/guides/agent/integrations/ ## MCP servers for the agent **Settings → AI → MCP servers for the agent** connects other MCP servers, such as GitHub, Jira, a database or your own service, to the Kurlo agent. Add an **HTTP** server with its URL and headers, or a **Local command** that Kurlo starts, such as `npx` with `-y` and `@modelcontextprotocol/server-github`, with its environment variables. **Test** connects and lists the tools, and says whether the server also has resources and prompts. Header and environment values are encrypted on this computer; to keep a saved value when you edit a server, leave its line as `NAME=`. For an HTTP server that asks you to sign in, such as Linear or Notion, set **Sign-in** to **OAuth sign-in** and save. **Sign in** in the list reads the server's metadata to find its authorization server, registers Kurlo there and opens the sign-in page in your browser; when you approve, the server shows **Signed in**. If the authorization server does not let apps register themselves, create an app there and enter its **Client ID**. Kurlo uses PKCE and asks for a token for that server only. The tokens are encrypted on this computer and renewed when they expire; when that fails, the agent tells you to sign in again. **Sign out** forgets them. Each turn the agent sees the tools of every server that is on, named `server__tool`. Every call waits for your approval, showing the server, the tool and its arguments, unless you choose **Allow for this chat** or an approved plan lists it as `server.tool`. A server that offers resources or prompts also gets `server__resources_list`, `server__resource_read`, `server__prompts_list` and `server__prompt_get`, so the agent can read its documents or fill in its prompt templates. These only read, so they run without asking. Answers from these servers are treated as data, not instructions. **Turn off** keeps a server without offering its tools. Calls appear in the [activity log](https://kurlo.dev/docs/guides/agent/activity/#agent-activity) under the server and tool name. ## Git Git works on the whole folder, not on one workspace: when a folder holds several workspaces, a branch or commit made from one chat applies to all of them, and **Chat details → Git** says so. When the workspace is in a Git repository, the agent can check `git status` and the diff of the workspace files, create a branch, commit and push. Creating a branch and committing wait for your approval; a commit card lists every file with its diff and a **Commit** button. A push asks every time, even after **Allow for this chat**, and the agent pushes only when you ask it to. Only Kurlo workspace files are ever committed: other files in the repository are left alone. To keep the agent's work apart from yours, turn on **Branch** in the message box before you send. Kurlo then commits each change you approve to a branch of its own, named after the chat, such as `kurlo-agent/cover-orders-1a2b3c`. The branch is created from the current commit on the first change and the workspace switches to it, so uncommitted edits you had in a file the agent changes go into that commit too. A change you reject is not committed. **Chat details → Git** shows the current branch and the agent branch. **Open pull request** in **Chat details** opens the page that starts a pull request for the current branch on GitHub, or a merge request on GitLab and Bitbucket, against the remote's default branch. Push the branch first. Kurlo builds the link from the remote URL and sends nothing; for other hosts it says it cannot build one. # Chats and the activity log Source: https://kurlo.dev/docs/guides/agent/activity/ Chats are kept on this computer in Kurlo's profile, encrypted like the [request history](https://kurlo.dev/docs/guides/history/), and not in the workspace files, so they never end up in Git. Each chat belongs to the workspace selected in the top bar when you start it. The agent in that chat sees and changes only that workspace: its collections, requests and environments. Other workspaces in the same folder are out of its reach, and new collections and environments go into the chat's workspace. Switching workspaces shows that workspace's chats and restores its open chat and selected agent when you return. Every chat, and the new chat, keeps its own unsent draft on this computer: it stays when you switch chats or workspaces, close the Agent tab or restart Kurlo, and disappears once you send it or clear the message box. A new chat is named after its first message; rename it by clicking its name in the header, double-clicking it in the sidebar, pressing `F2`, or choosing **Rename** in its **•••** menu, where **Delete** removes it. Kurlo keeps up to 200 unarchived chats across the local profile and removes them after 90 days of inactivity. A long chat opens at its latest messages; earlier ones load as you scroll up, with the mouse or with `Page Up` after `Tab` moves focus into the conversation. Use `Cmd/Ctrl K` to find a chat by its name alongside requests and commands. **Chats in this workspace** includes unarchived chats from the selected workspace. Selecting a result opens its agent and chat. Prefix the query with `>` to search commands only. To keep a chat, choose **Archive** from its **•••** menu in the sidebar. Open **Archived** to read saved chats for the current workspace. Archived chats stay encrypted and are kept until you delete them. Choose **Restore** in the chat menu to move a chat back to **Chats** and continue it. For Codex and Claude Code, continuing also requires the original session to be available in the connected agent. Choose **Export as Markdown…** in either list to save the full stored conversation, including saved tool calls and results. Review the warning and choose where to save the file. The Markdown copy is unencrypted and can contain sensitive information. ## Agent activity Every tool call, by the Kurlo agent, Codex, Claude Code or an assistant connected through `kurlo mcp`, is also written to a local activity log with the files it changed, before and after. Open **Activity** at the top of the agent sidebar to see it. It shows the calls made in the workspace selected in the top bar; choose **All workspaces** to see calls from every workspace and folder, each marked with where it happened. A call from a `kurlo mcp` client belongs to the workspace whose files it changed; a call that only read belongs to none and shows only under **All workspaces**. Calls are listed newest first under **Today**, **Yesterday** and **Earlier**; search by tool, file, branch or commit, or narrow the list to one client. The search covers the whole log, not only the calls on screen, and older calls load as you scroll to the end. The summary counts every call of the last seven days. A grey dot marks a declined or restored call, a red one an error. The list updates by itself when an agent turn ends and when you come back to Kurlo. With no call selected, the screen sums up the calls of today and the last 7 days, the errors among them and the calls that changed files. **Recent changes** lists the latest calls that changed files, and **Errors and declined** the calls that failed or that you declined; select a row to open the call. Select a call to see its client, time, arguments and result, the branch and commit it made, and the diff of each file it changed. The close button at the top right returns to the summary. **Restore** puts a file back to its version from before the call, and **Restore all** does it for every file of the call. Kurlo refuses when the file has changed since, so it never overwrites later work; restore that file from Git instead. Files over 512 KB are listed without their content and cannot be restored here. **Open chat** opens the chat the call came from when that chat is in the current workspace; for a call from another workspace, switch to that workspace in the top bar first. The log is encrypted, kept for 30 days or 2,000 calls, and stores arguments and results with secrets masked and cut at 16 KB. In the **•••** menu of the summary, **Pause recording** stops logging new calls and **Clear activity…** deletes the whole log. ## Limits - The agent sees the workspace, its environments and Kurlo's history. Source access is limited to the read-only folder you connect to the chat. - One turn runs at a time in each chat, and a turn stops after 50 model steps. Reading tools called in the same step run together. - For the Kurlo agent using an API connection, the model gets the last two exchanges in full. Tool results from earlier ones are shortened to about 500 tokens, and when the chat outgrows 70% of the model's context window its oldest exchanges are left out; the agent is told so and asks if you refer to them. Very large tool results are kept in the chat up to 64 KB. - Small local models often call tools badly. Models marked **Recommended** in Settings → AI handle them well. # MCP server (kurlo mcp) Source: https://kurlo.dev/docs/guides/mcp-server/ > Let Claude, Codex, Cursor and other AI assistants run your saved Kurlo requests and keep your collections up to date through the Model Context Protocol. `kurlo mcp` serves a Kurlo workspace to AI assistants as a [Model Context Protocol](https://modelcontextprotocol.io) server. Once it is connected, an assistant can see your collections and environments, run a saved request and read the response, run a collection's tests, or send a one-off call that uses your environment's variables. It does this with the same engine as the app and [`kurlo run`](https://kurlo.dev/docs/guides/cli-runner/). It can also write to the workspace: add and change saved requests with their tests, write tests from a response, save responses as examples and set environment variables. An agent that adds an endpoint to your service can add the request for it in the same commit, and Kurlo, if it is open, shows the change within a second. The assistant starts `kurlo mcp` itself and talks to it over stdin and stdout. The server comes from the [`@kurlo/cli`](https://www.npmjs.com/package/@kurlo/cli) npm package, which `npx` downloads on first use. You can [connect an assistant](https://kurlo.dev/docs/guides/mcp-server/connect/) with or without the desktop app installed. # Connect an assistant Source: https://kurlo.dev/docs/guides/mcp-server/connect/ One command adds Kurlo to every AI client it finds on your machine: Claude Code, Claude Desktop, Codex, Cursor, VS Code, Windsurf and Gemini CLI. ```bash npx -y @kurlo/cli mcp install --env Local ``` It prints what it changed in each client's config and leaves everything else in those files as it was. Run it again after changing the flags and it updates the entries; run `kurlo mcp uninstall` to take them out. Name clients to set up only those, such as `kurlo mcp install cursor codex`, and add `--dry-run` to see the changes first. | Flag | Meaning | |------|---------| | `--env NAME` | Environment the server uses when a call does not name one. | | `--workspace DIR` | Serve this workspace instead of the one the app has open. | | `--read-only` | Install the server with only the tools that read and run. | | `--project` | Write the project's shared config instead of yours. See below. | | `--command PATH` | How clients start Kurlo: `npx`, or the path to a `kurlo` binary. | | `--name NAME` | Server name in the clients' config, `kurlo` by default. | | `--dry-run` | Show what would change, change nothing. | When the Kurlo app is installed, clients start the server from the app's own binary, even if you ran the command through `npx`: apps opened from the Dock or Start menu often cannot find `npx`. Without the app, they start it with `npx -y @kurlo/cli`. Claude Code is set up with `claude mcp add` when the `claude` command is available, and otherwise in `~/.claude.json`. A config file with comments in it is not changed; Kurlo prints the entry to add by hand instead. Restart Claude Desktop, Windsurf and running Claude Code sessions to pick up the change. ## Share it with your team Run it with `--project` in a repository that holds a Kurlo workspace, and it writes the project's own config instead: `.mcp.json`, which Claude Code and VS Code read, and `.cursor/mcp.json` when the project uses Cursor. Commit them, and everyone who opens the repository in one of those clients gets the Kurlo server for that workspace. ```bash npx -y @kurlo/cli mcp install --project --env Local ``` It finds the workspace in the current folder or a folder right inside it, such as `./api-tests`, and records it as a relative path. The entries always start Kurlo with `npx`, so they work on every teammate's machine. # Configure an MCP client manually Source: https://kurlo.dev/docs/guides/mcp-server/manual-setup/ ## By hand **Claude Code** ```bash claude mcp add kurlo -- npx -y @kurlo/cli mcp --env Local ``` **Codex** (CLI, IDE extension and desktop app share one config) ```bash codex mcp add kurlo -- npx -y @kurlo/cli mcp --env Local ``` or in `~/.codex/config.toml`: ```toml [mcp_servers.kurlo] command = "npx" args = ["-y", "@kurlo/cli", "mcp", "--env", "Local"] ``` **Claude Desktop, Cursor and other clients with a JSON config** (`claude_desktop_config.json`, `.cursor/mcp.json`, …) ```json { "mcpServers": { "kurlo": { "command": "npx", "args": ["-y", "@kurlo/cli", "mcp", "--env", "Local"] } } } ``` ## Without Node.js The desktop app is the same server. Point the client at its binary instead of `npx`: `/Applications/Kurlo.app/Contents/MacOS/kurlo` on macOS, or the installed `kurlo` executable on Linux and Windows. ```bash claude mcp add kurlo -- /Applications/Kurlo.app/Contents/MacOS/kurlo mcp --env Local ``` With no workspace argument, the server uses the workspace the app has open, including the secret values the app keeps on this machine. To serve a different [Git-backed workspace](https://kurlo.dev/docs/guides/git-workspaces/), pass its folder (the one that contains `kurlo.yml`) as the first argument: ```bash kurlo mcp ~/code/payments-api/kurlo --env Staging ``` The workspace is read again on every call, so a request you edit in the app is what the assistant runs next. In the other direction, the app notices files the assistant wrote and reloads them. If you were editing at that moment, both changes are kept: see [Working alongside the app](https://kurlo.dev/docs/guides/mcp-server/sessions/#working-alongside-the-app). # MCP tools Source: https://kurlo.dev/docs/guides/mcp-server/tools/ ## Tools | Tool | What it does | |------|--------------| | `list_requests` | Lists saved requests with their path (`Collection/Folder/Name`), id, protocol, method and URL. Can be filtered to one collection, and searched with `query`: every word has to appear in the path, method or URL, so `post orders` finds `POST /orders`. | | `get_request` | Shows how one request is defined: method, URL, query parameters, headers, body, auth type, scripts and browser settings, plus its saved [examples](https://kurlo.dev/docs/guides/examples/) with their status, content type and body, so the assistant can compare a live response with the expected one. Credentials are left out: secret rows show ``, and a value typed straight into an `Authorization`, `Proxy-Authorization`, `Cookie` or `X-API-Key` header shows `[secret]`. A header that holds only a `{{variable}}` is shown as written. | | `list_environments` | Lists environments and their variables. Secret values are hidden. | | `check_openapi_sync` | For a collection connected to an [OpenAPI source](https://kurlo.dev/docs/guides/openapi-sync/), downloads the current spec and lists the operations added, changed, moved or removed since the last sync applied in Kurlo. It changes nothing; you review and apply the changes in the app. Protected environments cannot be used to resolve the source URL. | | `run_request` | Sends a saved HTTP, GraphQL, unary gRPC, MCP or AI request. HTTP responses include timings, redirects and TLS details. For MCP, pass `mcpMethod` as `tools/list` or `tools/call`. Pass `mcpName` and `mcpArguments` to call a tool, and `mcpCursor` to read another page. | | `run_collection` | Runs HTTP, GraphQL and unary gRPC requests in order, with per-request results and assertions. Use `iterations`, `delayMs`, `failFast` and a workspace-relative CSV or JSON `dataFile`. A data file runs one iteration per row. Pass a `progressToken` for progress after each request. | | `send_request` | Sends an unsaved HTTP request. `{{variables}}` in the URL, headers and body are resolved from the environment. | | `list_history` | Lists the requests you recently sent from the Kurlo app, newest first, with status, timing and the saved request each came from. Can be searched, or narrowed to failures. | | `get_history_entry` | Shows one request you sent from the app and the response you got: status, headers, body, error, test results and script logs. Without an entry it shows the last one. | | `diagnose_last_failure` | Explains why a request sent from the app failed. See [When a request fails](https://kurlo.dev/docs/guides/mcp-server/diagnostics/#when-a-request-fails). | | `import_preview`, `import_apply` | Preview imported YAML, then confirm and apply that preview. | | `list_files`, `read_file`, `search_code` | List, read or search the read-only source folder supplied with `--project-root`. | | `get_docs`, `save_docs` | Read or replace Markdown docs for a saved request or collection. | | `code_snippet` | Generate a snippet in cURL, HTTPie, JavaScript, Node.js, Axios, Python, Go, Java, C#, PHP, Ruby, Swift, Kotlin or Rust. | | `sync_collection`, `cover_endpoint` | Get a workflow for using the connected source folder to update collection coverage. | | `list_load_tests`, `get_load_test`, `save_load_test` | List, read or save a collection's load tests. Omit the test ID to create a test, or keep it to replace its definition. | | `start_load_test`, `load_test_status`, `stop_load_test` | Start k6 in the background, inspect progress or stop the active run. | | `list_load_runs`, `load_test_result`, `compare_load_runs` | Find completed runs and compare their summaries by test ID and `startedAt` timestamp. | | `start_mock_server`, `mock_server_log`, `stop_mock_server` | Serve a collection's saved examples on localhost, check the recent request log or stop the server. | | `list_cookies`, `clear_cookie_jar` | Inspect cookie metadata for a domain or clear the jar used by this MCP connection. | | `create_collection` | Creates an empty collection. | | `save_request` | Creates or edits any supported request type using workspace YAML. The HTTP and GraphQL shorthand is also available. | | `patch_request` | Changes individual fields of a saved request with JSON Merge Patch. | | `list_globals` | Reads globals in the active local profile. Secret values are hidden. | | `authorize_oauth2` | Authorizes a saved request for the current session. See [OAuth 2.0 sign-in](https://kurlo.dev/docs/guides/mcp-server/edit/#oauth-20-sign-in). | | `apply_changes` | Applies an ordered batch of workspace edits. Agent Mode reviews the combined diff once. | | `delete_request` | Deletes a saved request and its examples. | | `save_example` | Saves a response as an [example](https://kurlo.dev/docs/guides/examples/) of a request: the response of the last `run_request` of that request, or one the assistant describes with `status` and `body`. | | `set_variable` | Sets a non-secret variable in an environment, and creates the environment if there is none with that name. | | `generate_tests` | Writes a request's status, `Content-Type` and JSON schema tests from a real or described response. See [Tests from a response](https://kurlo.dev/docs/guides/mcp-server/prompts/#tests-from-a-response). | | `git_status` | Shows the branch, its upstream, commits ahead and behind, and which workspace files have uncommitted changes. | | `git_diff` | Shows the uncommitted diff of the workspace files or one file; with `outgoing`, the committed changes not pushed yet. | | `pull_request_url` | Builds the link that starts a pull request for the current branch on GitHub, or a merge request on GitLab and Bitbucket. | | `git_create_branch` | Creates a branch from the current commit and switches to it. | | `git_commit` | Commits uncommitted workspace files, or only the `paths` given, with a `message`. Other files in the repository are never committed. | | `git_push` | Pushes the current branch to its remote, never with force. The assistant is told to push only when you ask. | A request can be named by its id, its full path, or just its name when that name is unique. When a name matches more than one request, the tool lists the matches with their ids so the assistant can pick one. Request and collection runs accept an `environment` and a `variables` object of overrides for that call. `run_request` and `send_request` return up to 64 KB of the response body by default. An assistant can ask for up to 1 MB with `maxBodyBytes`. Binary bodies are described but not included. Live connection tools are available in the desktop app’s [Agent Mode](https://kurlo.dev/docs/guides/agent/requests/). A mock or k6 run started through `kurlo mcp` belongs to that process and stops when it exits. The cookie jar is local to the process. ## Import requests and read project source Start the server with `kurlo mcp /path/to/kurlo-workspace --project-root /path/to/source`. Source paths for `list_files`, `read_file` and `search_code` are relative to the connected folder. The server skips symlinks, hidden configuration, credential files and common dependency and build directories. These tools only read the source. Workspace tools still operate on the Kurlo workspace supplied separately. Call `import_preview` with a relative `file`, pasted `content` or an OpenAPI `url`. A file path is relative to the source folder when supplied and otherwise to the Kurlo workspace. Supported inputs include OpenAPI and Swagger, Postman v2 collection JSON, Insomnia Export v4 JSON, HAR, and cURL. For Postman v3 Native Git folders, use the [desktop importer](https://kurlo.dev/docs/guides/import-export/postman/#postman-v3-folders). Format detection is automatic, or you can pass `format` explicitly. For a spec with external references, bundle it into one file before importing. The preview reports the intended collection, requests and environments and shows the YAML diff. Omit `collection` to create a collection, or supply its name or ID to append requests. Pass `workspace` when the Kurlo folder contains multiple workspaces and you are creating a collection. If the diff spans several pages, call `import_preview` again with the `importId` and `nextOffset` as `offset`. Review the result and pass its `importId` and `confirm: true` to `import_apply`. A file changed since the preview requires a new preview. Agent Mode asks you to approve the diff in the chat. # Prompts and tests Source: https://kurlo.dev/docs/guides/mcp-server/prompts/ ## Prompts The server also offers three [prompts](https://modelcontextprotocol.io/specification/2026-07-28/server/prompts): ready-made instructions that clients show as commands. In Claude Code they are `/mcp__kurlo__sync_collection` and so on. | Prompt | Arguments | What the assistant does | |--------|-----------|-------------------------| | `sync_collection` | `collection`, `source` | Finds the HTTP routes in your project's code (Express, FastAPI, Flask, Go routers, Spring, Rails, ASP.NET and others), matches them with the saved requests, and adds a request with tests for each route that has none. It deletes nothing: saved requests that match no route are listed for you to decide. | | `cover_endpoint` | `endpoint` (required), `collection` | Does the same for one endpoint, such as `POST /orders`, and also saves its main error responses as examples. | | `debug_last_failure` | `entry` | Calls `diagnose_last_failure`, explains the cause and proposes a fix, which it applies only after you agree. | Requests are saved with `{{baseUrl}}` in the URL, so the address lives in an environment, not in each request. When no environment sets it, the prompts tell the assistant to look for it in the project (`docker-compose.yml`, launch settings, the README) and to ask you before calling `set_variable`, and never to point an environment at production. With `--read-only` only `debug_last_failure` is offered. ## Tests from a response `generate_tests` writes a saved request's tests for it. With `from: run`, the default, it sends the request and writes three `pm.test` checks from the response: - the status, such as `pm.response.to.have.status(200)`; - the `Content-Type`; - a JSON schema of the body, checked with `pm.response.to.have.jsonSchema`: the type of every field and which fields are required. Values are left out, so the tests do not break when the next order has another id, and nothing from the response is written into the request's file. The response is also saved as an [example](https://kurlo.dev/docs/guides/examples/), named after its status, so the [mock server](https://kurlo.dev/docs/guides/mock-server/) serves it. Run `generate_tests` again later and an example of the same name is refreshed rather than added twice. Sending the request has its effects: a `POST` creates what it creates. A response with a 4xx or 5xx status is refused, since the tests would assert a failure, unless the call passes `allowErrorStatus: true` to test that error on purpose. When the API is not running anywhere yet, `from: example` takes what the code returns instead: a `status` and a `body`, or a `schema` built from the response type. The tests and the example are written the same way, and the tests pass once the server is up. A schema that does not accept its own body is refused. Tests the request already has are kept and the new ones are added after them. A test with the same name, such as `status is 200`, is not added twice. When the request's tests already expect another status, an error response such as a `422` is saved as an example only, so the script never asserts two statuses. `replace: true` replaces the whole test script. # Diagnose API requests Source: https://kurlo.dev/docs/guides/mcp-server/diagnostics/ ## When a request fails `diagnose_last_failure` takes the most recent request sent from the app that got no response, a 4xx or 5xx status, or failing tests, or the history entry you name, and returns: - the status, the error and the failed tests; - `unresolvedVariables`: the `{{variables}}` the request uses that nothing sets in the environment active in the app; - `example`: how the response differs from the request's saved example, with missing fields, fields that changed type and a different status; - `hints`: the likely cause in plain words, such as a server that is not running, a host that does not resolve, a `401` because the login request has not set `{{token}}` yet, a method typed into the URL field, or a pre-request script that threw. It only reads, so it is there with `--read-only` too. ## What you just sent from the app The assistant can read the requests you send from the Kurlo app, so you can debug together without copying anything: send a request, then ask "why did my last request fail?" `get_history_entry` with no arguments returns the last request sent from the app with its response, test results and script logs, and `list_history` finds older ones, such as every request that failed today. These tools read the [history](https://kurlo.dev/docs/guides/history/) that Kurlo keeps on this machine, for every workspace, including requests you never saved. Secrets are masked as everywhere else: values Kurlo stores as secrets, auth credentials and the values of headers like `Authorization` and `Cookie` come back as `[secret]`. Both tools only read, so they are also there with `--read-only`. # Writing to the workspace Source: https://kurlo.dev/docs/guides/mcp-server/edit/ The write tools change the same YAML files the app writes, through the same code, so the result looks exactly as if you had made it in the app. In a [Git-backed workspace](https://kurlo.dev/docs/guides/git-workspaces/) every change shows up in Git, and a deletion can be undone from history. Each result names the file it wrote. For the HTTP and GraphQL shorthand, `save_request` without `request` creates a request. It needs a `url`, and a `collection` unless the workspace has only one. With `request`, the id or path of an existing one, it changes only the fields the call passes. `params`, `headers` and `form` replace the whole list. `folder` puts the request in a folder, creating it if needed, and `collection` moves it to another collection. The other fields are: | Field | Meaning | |-------|---------| | `name` | Defaults to the method and path, such as `POST /orders`. | | `type` | `http` (the default) or `graphql`. | | `method`, `url` | `url` may use `{{variables}}`, such as `{{baseUrl}}/orders`, and `:name` path variables, such as `/orders/:orderId`. | | `pathVariables` | Values for the URL's `:name` segments, such as `[{"key": "orderId", "value": "{{orderId}}"}]`. Replaces the whole list. `get_request` returns them under the same name. | | `body`, `bodyType` | A JSON body is stored as JSON and anything else as text, unless `bodyType` says `xml`, `html`, `urlencoded`, `form` or `none`. | | `query`, `variables` | The query and variables of a GraphQL request. | | `auth` | `inherit` (the default, the collection's auth), `none`, `bearer` with `token`, `basic` with `username` and `password`, or `apikey` with `key`, `value` and `in`. | | `preRequestScript`, `testScript` | JavaScript with the [Postman `pm.*` API](https://kurlo.dev/docs/reference/scripting-api/). `pm.test` calls in `testScript` become the request's tests, which `run_request` and `run_collection` report. | | `assertions` | [Checks without code](https://kurlo.dev/docs/guides/scripting/assertions/), such as `[{"target": "status", "operator": "eq", "value": "201"}]`. Operators: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `notIn`, `contains`, `notContains`, `matches`, `exists`, `notExists`, `type`, `length`. Replaces the whole list; `[]` removes them. `get_request` returns them, and `run_request` reports them with the tests. | | `notes` | Notes shown with the request. | ## Workspace YAML and partial edits Pass the `yaml` argument to `save_request` for HTTP (including SSE), GraphQL, WebSocket, Socket.IO, gRPC, MCP or AI requests. Use a single `version: 1` document with a `request` mapping and the fields in the [workspace format](https://kurlo.dev/docs/reference/kurlo-yaml-format/request/). Kurlo can assign the request ID. Pass `collection` to choose the target collection or use `collectionId` in the document. Use `request` to edit an existing request. Call `get_request` with `format: "yaml"` to inspect its workspace fields, including protocol-specific settings. The output omits stored credentials. Pass `request` and a `patch` object to `patch_request`. It merges nested objects, replaces arrays and removes fields set to `null`. For example, `{"request":"Orders/List orders","patch":{"requestNotes":"Returns recent orders"}}` changes only the notes. Use the workspace field names for authentication, client certificate settings and scripts. NTLM uses `auth.type: ntlm`, `basicUser` and `basicPass`. ## Batch edits Pass an `operations` array to `apply_changes`. Each entry has a `tool` name and an `arguments` object. Operations run in order, so an edit can refer to a request created earlier in the batch. If validation fails, Kurlo saves none of the edits. In Agent Mode, all affected files appear in one review with one **Apply** button. The results from `run_request` and `run_collection` include the logs from collection, folder and request scripts. | Operation | Arguments | |-----------|-----------| | `create_collection`, `save_request`, `patch_request`, `delete_request`, `save_example`, `set_variable` | Same arguments as the standalone tools. | | `duplicate_request` | `request` and an optional `patch` for the copy. | | `patch_collection` | `collection` and `patch` for the name, description, defaults, folder paths or folder defaults. Set scripts and authentication in `defaults` or `folderDefaults`. | | `move_folder`, `duplicate_folder` | `collection`, `from` and `to` as slash-separated folder paths, and optional `targetCollection`. Includes nested requests and folder defaults. | | `duplicate_collection` | `collection` and optional `name`. Copies requests, examples and defaults. | | `create_environment`, `patch_environment`, `delete_environment` | Create with `name` and optional `workspace` and `patch`. Update with `environment` and `patch` for `name`, `parentId` or `values`; `values` replaces the whole list. `values` (or `variables`) is a list of `{key, value}` rows with optional `description` and `enabled`, or an object such as `{"baseUrl": "https://api.example.com"}`, so one batch can create many environments with their variables. Rows marked `secret` are refused: add secrets in the app. Delete with `environment`. | | `patch_example`, `delete_example` | `request` and `example` by name or ID. Pass a `patch` object to edit the example. | | `edit_global` | `key` and `value` to create or update, `name` to rename, or `delete: true` to remove. Open the workspace in Kurlo first. | Globals stay in the encrypted local profile. Agent Mode shows global edits alongside workspace files in the same review. Set secret globals in Kurlo. ## OAuth 2.0 sign-in Call `authorize_oauth2` with a saved request ID or path and, if needed, its environment. For Authorization Code and Device Code, approve the call and finish sign-in in your browser. An external MCP client needs to request progress notifications to receive the URL or device code. Client Credentials and Password use the saved configuration directly. Tokens stay in memory for the current Agent Mode turn or external MCP connection and stay out of tool results. ## Secrets stay out The write tools never put a secret in a file. A bearer token, password or API key value has to be a variable reference such as `{{apiToken}}`, and a literal value is refused. Add the value in the app as a variable marked secret, and the request uses it. Existing secrets are masked on reads. Omit fields containing saved secrets from a patch to preserve them. The YAML and patch tools accept normal variable references in authentication fields and refuse internal vault placeholders. # Read-only mode and protected environments Source: https://kurlo.dev/docs/guides/mcp-server/permissions/ ## Read-only Start the server with `--read-only` to offer only the tools that read and run. The write tools, `git_create_branch`, `git_commit` and `git_push` are then left out of the tool list, and calling one is refused. ## Protected environments Mark an environment **Protect from AI agents** in its ⋯ menu in the app, and `kurlo mcp` refuses every call that would use it: `run_request`, `run_collection`, `send_request` and `start_load_test` with that environment, and edits to it through `set_variable` or `apply_changes`. The assistant is told to ask you to run the request in the app instead. Use it for production and anything else an assistant should not reach by picking the wrong environment. The mark is saved in the environment's file as `protected: true`, so in a Git-backed workspace it applies to everyone on the team. `list_environments` shows it. An environment that [inherits](https://kurlo.dev/docs/guides/environments/manage/#inheriting-from-another-environment) from a protected one is protected too; `list_environments` names its parent under `inherits` and lists the variables it inherits. # Session behavior and secrets Source: https://kurlo.dev/docs/guides/mcp-server/sessions/ ## Working alongside the app The app and `kurlo mcp` can have the same workspace open. They take turns writing it, so neither reads the other's half-written save. The app learns about files changed outside it from the operating system (FSEvents on macOS, `ReadDirectoryChangesW` on Windows, inotify on Linux) and reloads them within about a second, with a short notice; where that is unavailable it checks the folder once a second instead. If the app saves before it has reloaded, for example because you were typing in a request at that moment, it writes your edits and then puts back every file changed outside it that your edits did not touch. Only when both changed the same file does the app's version win. The same protection covers files changed by an editor or by `git pull` in a terminal. ## Checking a call the way a browser would An API call that works from the assistant can still be refused in the browser, where CORS applies. `run_request` and `send_request` take `browserOrigin`, the origin of the page that would make the call, such as `https://app.example.com`. Kurlo then sends it with [browser emulation](https://kurlo.dev/docs/guides/browser-security/): browser headers and `Origin`, the CORS preflight when the method or headers need one, and the CORS error a browser would raise, in the result's `error`. Add `browserCredentials: true` for a call made with `credentials: 'include'`, which a wildcard `Access-Control-Allow-Origin` does not satisfy. A saved request that already has browser emulation turned on, by itself or through its collection, is sent with those settings even without `browserOrigin`. ## Variables carry across calls A value a script sets with `pm.environment.set` or `pm.collectionVariables.set` is kept for the rest of the session, per environment. An assistant can run your login request once, and the token it stores is used by every request after it, just as in a collection run. Each result lists the variables the call changed in `variablesChanged`. These values live only in the server's memory. They are not written back to the workspace, and they are gone when the assistant restarts the server. When a request uses a `{{variable}}` that no environment, call override or script has set, the result lists it in `unresolvedVariables`. The request is still sent with the placeholder as written, so a `401` next to `unresolvedVariables: ["token"]` tells the assistant to run the login request first or pass the value in `variables`. Cookies and OAuth 2.0 tokens are kept for the session too. OAuth works the same way as [in `kurlo run`](https://kurlo.dev/docs/guides/cli-runner/oauth/): Client Credentials and Password grants are fetched, and browser grants use their refresh token. ## Secrets Environment variables marked secret are used when requests are sent, but they are masked as `[secret]` in everything returned to the assistant. That covers the resolved URL, response headers and body, test messages and script logs. A server that echoes your token back does not hand it to the model. `list_environments` shows only the names of secret variables, and `get_request` never includes credentials. The write tools never store a secret either: see [Secrets stay out](https://kurlo.dev/docs/guides/mcp-server/edit/#secrets-stay-out). # CLI flags and protocol Source: https://kurlo.dev/docs/guides/mcp-server/reference/ ## Flags | Flag | Meaning | |------|---------| | `--env NAME` | Environment used when a call does not name one. | | `--timeout MS` | Per-request timeout, overriding request settings. | | `--insecure`, `-k` | Turn off TLS certificate verification for every request. | | `--allow-send-request` | Let scripts call `pm.sendRequest`. Off by default, as in `kurlo run`. | | `--project-root ` | Connect a read-only source folder for project tools and file imports. | | `--read-only` | Offer only the tools that read and run. | ## Docs for agents The whole Kurlo documentation is available in plain text for language models: [llms.txt](https://kurlo.dev/llms.txt) lists the pages, and [llms-full.txt](https://kurlo.dev/llms-full.txt) has all of them in one file. ## Protocol The server speaks MCP over stdio with newline-delimited JSON-RPC. It supports the `initialize` handshake of the 2024-11-05 through 2025-11-25 revisions, and the stateless 2026-07-28 revision's `server/discover`. It offers tools and prompts, and no resources. Tool results carry the JSON as text and as `structuredContent`. A call can be cancelled with `notifications/cancelled`. To try the server by hand, pipe JSON-RPC into it: ```bash printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_requests","arguments":{}}}' | kurlo mcp ``` # Code snippets Source: https://kurlo.dev/docs/guides/code-generation/ > Copy an HTTP, GraphQL or AI request as a runnable snippet in one of 14 targets. The **Code** side panel turns the currently-open request into a runnable snippet. Open it with the **Code snippet** (``) button next to **Send**, or run **Show code snippet** from the [command palette](https://kurlo.dev/docs/guides/workspaces/command-palette/). ## Supported targets Kurlo currently exposes 14 choices: | Family | Targets | |--------|---------| | Command line | cURL, HTTPie | | JavaScript | JavaScript `fetch`, Node.js `fetch`, Axios | | General purpose | Python `requests`, Go `net/http`, Java OkHttp, C# `HttpClient` | | Additional clients | PHP cURL, Ruby `Net::HTTP`, Swift `URLSession`, Kotlin OkHttp, Rust `reqwest` | ## What gets generated Snippets are generated from the currently open HTTP, GraphQL or AI request: - Non-secret variables are expanded from the active environment and collection variables. - Secret variables stay as `{{name}}` placeholders so copying a snippet does not silently disclose them. - URL params, enabled headers, and supported bodies are represented. - Bearer, API key, Basic, and OAuth 2.0 auth are emitted in every language. Basic becomes an `Authorization: Basic …` header; an OAuth 2.0 request carries the access token Kurlo currently holds, and the snippet says so, because that token expires. - cURL goes further where curl itself can: `-u` for Basic, `--digest` for Digest, and `--aws-sigv4` with the access key for AWS Signature v4, so the copied command signs itself rather than carrying a signature that is already stale. - OAuth 1.0 is signed per request over a fresh timestamp and nonce, so a snippet cannot carry a signature that still works. It leaves the header out and says to use an OAuth 1.0 signing library. ## AI requests An [AI request](https://kurlo.dev/docs/guides/request-types/ai/#ai) becomes the HTTP call Kurlo makes for the first message: a `POST` to the full address shown under the base URL, such as `https://openrouter.ai/api/v1/chat/completions` or `https://api.anthropic.com/v1/messages`, with a JSON body that holds the model, the system prompt, the prompt and the settings you set (temperature, Top P, max tokens, streaming, and thinking for Anthropic). Anthropic snippets also carry the `anthropic-version` header. API keys follow the same rules as other requests: a secret `{{openaiApiKey}}` stays a placeholder. Replies in the chat and MCP tools from the Tools tab are not part of the snippet: tools are listed from their servers when you send, and each step depends on the model's answer. ## What's omitted - Pre-request scripts. Snippets show the wire-level request, not the steps that produced it. If your auth depends on a token fetched in a script, copy that call separately. - Test scripts — they're a Kurlo concept, not a client concept. - Digest and AWS Signature v4 outside cURL. Neither can be written as a fixed header — Digest answers a challenge, SigV4 signs each request — so the snippet opens with a comment saying which scheme it is and what to reach for in that language, rather than looking complete and returning 401. - Binary and multipart file handling varies by target; cURL has the most complete file-body output. :::caution Treat generated snippets as a starting point and review them before sharing. Literal auth values already present in the request, such as a Bearer token or API key, can appear in the output. ::: ## Copy + paste workflow The button copies to clipboard and shows a toast. There's no "save snippet to file" affordance — by design, snippets are throwaway artefacts for sharing in bug reports and chat threads. # Scripting API Source: https://kurlo.dev/docs/reference/scripting-api/ > Look up pm.* methods for variables, requests, assertions, logs, and calls from scripts. Scripts run in a sandboxed JavaScript VM by default. The legacy [Tengo](https://github.com/d5/tengo) engine shares the core `pm.*` methods for request mutation, response assertions, variables, environments, and logs. The [scripting guide](https://kurlo.dev/docs/guides/scripting/) explains which features are specific to JavaScript. Module imports, process access, and filesystem access are disabled; `require` resolves only the [bundled stand-ins](https://kurlo.dev/docs/reference/scripting-api/compatibility/#require). Network access is disabled too, unless a request opts into [`pm.sendRequest`](https://kurlo.dev/docs/reference/scripting-api/send-request/). Execution is capped at 2 seconds by default — see [Script timeout](https://kurlo.dev/docs/reference/scripting-api/send-request/#script-timeout). # pm.request Source: https://kurlo.dev/docs/reference/scripting-api/request/ | Method | Description | |--------|-------------| | `pm.request.url` | Current request URL (string) | | `pm.request.method` | HTTP method | | `pm.request.auth` | Effective authentication details for JavaScript scripts | | `pm.request.headers.get(name)` | Get request header | | `pm.request.headers.set(name, value)` | Set / override header | | `pm.request.headers.unset(name)` | Remove header | | `pm.request.params.get(name)` | Get query param | | `pm.request.params.set(name, value)` | Set query param | | `pm.request.pathVariables.get(name)` | Get the value of the `:name` path variable | | `pm.request.pathVariables.set(name, value)` | Set a path variable's value before sending | | `pm.request.pathVariables.has(name)` | Whether the request has that path variable | | `pm.request.pathVariables.toObject()` | All enabled path variables as `{ name: value }` | | `pm.request.set_url(url)` | Override URL before sending | Header and parameter writes are an upsert, matching Postman: the first row with that name takes the new value, further rows with the same name are dropped, and a name the request does not have is appended. A row the script never names is left exactly as it was written — including two rows that share a name, which is how a repeated query parameter (`?tag=a&tag=b`) or a multi-valued header survives a script untouched. | `pm.request.body.raw` | Raw request body — readable and writable | | `pm.request.body.mode` | Body mode, in Postman's names: `raw`, `urlencoded`, `formdata`, `file`, `graphql`, `none` | | `pm.request.body.json()` | Body parsed as JSON | | `pm.request.body.update(value)` | Replace the body; objects are stringified | | `pm.request.body.urlencoded` | Field list — only when the mode is `urlencoded` | | `pm.request.body.formdata` | Field list — only when the mode is `formdata` | ## Reading request authentication JavaScript pre-request and test scripts can read the active authentication method for HTTP, GraphQL, and gRPC requests. This includes auth inherited from the collection or folder. Template values are resolved for the current request. ```js const auth = pm.request.auth if (auth.type === "bearer") { const token = auth.bearer.get("token") pm.expect(token).to.be.a("string") } ``` `auth.parameters()` returns the active method's parameter list. For example, `auth.parameters().get("username")` reads a Basic username, and `auth.apikey.get("in")` reads an API key's location. Use `.has(key)` to check for a parameter and `.toObject()` to read the list as key-value pairs. With **No Auth**, `auth.type` is `"noauth"` and the list is empty. The auth object is read-only. ## Rewriting and signing the body A pre-request script owns the body it writes: the value it sets is what goes on the wire, and a test script sees the same value afterwards. ```js const payload = pm.request.body.json() payload.timestamp = Date.now() pm.request.body.update(JSON.stringify(payload)) // Sign what will actually be sent pm.request.headers.set("X-Signature", pm.crypto.hmacSha256(pm.request.body.raw, pm.environment.get("secret"))) ``` Two things to know: - A body written onto a request that has **no body** is sent anyway — Kurlo picks `json` or `text` from the content. The same applies to a **binary** request with no file chosen yet. - A **binary** body read from a file is left alone. The script never sees those bytes, so it cannot replace them. ## Form and urlencoded bodies Those two modes are sent from their fields, not from raw text, so they are edited as a list. Writing `.raw` on them changes nothing, and Kurlo says so in the script log instead of dropping the write silently. ```js // mode === "urlencoded" pm.request.body.urlencoded.upsert({ key: "grant_type", value: "client_credentials" }) pm.request.body.urlencoded.add({ key: "scope", value: "read write" }) pm.request.body.urlencoded.remove("client_secret") const fields = pm.request.body.urlencoded.toObject() // { grant_type: "...", scope: "..." } ``` | Method | Description | |--------|-------------| | `.get(key)` / `.one(key)` | The value / the whole field | | `.has(key)` / `.count()` | Presence / number of fields | | `.add(field)` | Append `{ key, value, disabled?, type? }` | | `.upsert(field)` | Replace the field with that key, or append it | | `.remove(key \| predicate)` | Drop matching fields | | `.each(fn)` / `.all()` | Iterate / read the whole list | | `.clear()` / `.toObject()` | Empty the body / read it as an object | A file field keeps its attachment when a script rewrites its value; `type: "file"` marks it in the list. `pm.request.body.update({ mode: "urlencoded", urlencoded: [...] })` replaces every field at once. In Tengo the same surface is `pm.request.body`, `pm.request.body_type` (Kurlo's own names, not Postman's), and `pm.request.set_body(value)`. Tengo has no form-field API. # pm.response Source: https://kurlo.dev/docs/reference/scripting-api/response/ ## `pm.response` (test scripts only) | Method | Description | |--------|-------------| | `pm.response.code` | HTTP status code (int) | | `pm.response.status` | Status string, e.g. `"200 OK"` | | `pm.response.responseTime` | Duration in milliseconds (alias: `pm.response.time`) | | `pm.response.size` | Body size in bytes | | `pm.response.body` | Raw body as string | | `pm.response.json()` | Body parsed as JSON (map/array) | | `pm.response.headers.get(name)` | Get response header (case-insensitive) | | `pm.response.llm()` | AI requests only: the answer as `{ text, thinking, toolCalls, stopReason, model, usage, timing, steps, error }`, the same for every provider. `toolCalls` items have `id`, `name`, `input` and `server`; `usage` has `input`, `output`, `cacheRead`, `cacheWrite` and `reasoning`; `timing` has `firstToken` and `total` in milliseconds. | # Variable scopes Source: https://kurlo.dev/docs/reference/scripting-api/variables/ `pm.variables`, `pm.globals`, `pm.environment`, and `pm.collectionVariables` all expose the same four methods: | Method | Description | |--------|-------------| | `.get(key)` | Read a variable | | `.set(key, value)` | Write a variable | | `.unset(key)` | Delete a variable | | `.clear()` | Clear all variables | They differ in which scope they touch: | Scope | Reads | Writes | |-------|-------|--------| | `pm.variables` | All scopes, in precedence order: data row → request → environment → collection → session | The session scope | | `pm.globals` | The session scope | The session scope | | `pm.environment` | The active environment | The active environment | | `pm.collectionVariables` | The request's collection | The request's collection, saved back to the collection after the send | Kurlo has a single runtime variable scope, so `pm.globals` and `pm.variables.set` write to the same place — they are aliases, not two separate stores. **`pm.variables.replaceIn(text)`** fills every `{{name}}` in a string from the scopes above, plus `{{$guid}}` and the other [dynamic variables](https://kurlo.dev/docs/guides/environments/dynamic-variables/) — handy for signing the URL a request will actually hit. A name nothing defines is left as written. Globals persist. They are saved with your data, survive a restart, and are shared across every workspace. Edit them under **Environments → Globals** in the sidebar; a value a script writes appears there after the send. In [`kurlo run`](https://kurlo.dev/docs/guides/cli-runner/) they come from `--globals` / `--global-var` and can be written back with `--export-globals`. `pm.collectionVariables.set` persists: after the request finishes, the value is written onto the collection's variables (a Git-backed workspace records it in `collection.yml`). An existing row keeps its id, enabled state, secret flag, and description; only the value changes. ```js // Cache a value for every later request in the collection. pm.collectionVariables.set("lastOrderId", pm.response.json().id) ``` # Run context and cookies Source: https://kurlo.dev/docs/reference/scripting-api/context/ ## `pm.info` Read-only facts about the current run. | Property | Description | |----------|-------------| | `pm.info.requestName` | The request's name | | `pm.info.eventName` | `"prerequest"` or `"test"` | | `pm.info.iteration` | Current iteration (1-based) | | `pm.info.iterationCount` | Total iterations in this run | ## `pm.cookies` Read-only access to the cookies the request's jar would send for this URL. Domain, path, and `Secure` matching is already applied. | Method | Description | |--------|-------------| | `pm.cookies.get(name)` | Cookie value, or `undefined` | | `pm.cookies.has(name)` | Whether the cookie is present | | `pm.cookies.names()` | Array of cookie names | ## `pm.execution.skipRequest()` Called from a **pre-request** script, skips the send entirely. The request is reported as skipped rather than failed, so a conditional request does not fail a collection run or a `kurlo run` exit code. Calling it from a test script does nothing — the response already exists. ```js // Only hit the billing API when the environment opts in. if (pm.environment.get("mode") !== "live") pm.execution.skipRequest() ``` # pm.crypto Source: https://kurlo.dev/docs/reference/scripting-api/crypto/ Hashing, HMAC, and encoding, for signing requests. Every digest function takes an optional encoding — `"hex"` (default), `"base64"`, `"base64url"`, or `"latin1"`. | Method | Description | |--------|-------------| | `pm.crypto.md5(data, enc?)` | MD5 digest | | `pm.crypto.sha1 / sha256 / sha384 / sha512(data, enc?)` | SHA digest | | `pm.crypto.hash(algorithm, data, enc?)` | Digest under a named algorithm | | `pm.crypto.hmacSha1 / hmacSha256 / hmacSha384 / hmacSha512(data, key, enc?)` | HMAC | | `pm.crypto.hmac(algorithm, data, key, enc?)` | HMAC under a named algorithm | | `pm.crypto.base64Encode(data)` / `base64Decode(data)` | Base64 | | `pm.crypto.randomHex(bytes)` | Random hex string (default 16 bytes) | | `pm.crypto.uuid()` | Random v4 UUID | Supported algorithms: `md5`, `sha1`, `sha256`, `sha384`, `sha512`, `sha512-256`. An unknown name throws rather than signing with an empty digest. ```js // Sign the request the way a partner API expects. const ts = String(Date.now()) const sig = pm.crypto.hmacSha256(pm.request.method + "\n" + ts, pm.environment.get("apiSecret")) pm.request.headers.set("X-Timestamp", ts) pm.request.headers.set("X-Signature", sig) ``` ## `CryptoJS` A `CryptoJS` global is available for compatibility with scripts imported from Postman: `MD5`, `SHA1`, `SHA256`, `SHA384`, `SHA512`, the matching `Hmac*` functions, and `enc.Hex` / `enc.Base64` / `enc.Utf8`. It covers the digest and encoding calls that appear in real collections, not the whole library — for new scripts prefer `pm.crypto`. ```js const sig = CryptoJS.HmacSHA256("payload", pm.environment.get("secret")).toString() const b64 = CryptoJS.enc.Base64.stringify(CryptoJS.SHA256("payload")) ``` # pm.sendRequest Source: https://kurlo.dev/docs/reference/scripting-api/send-request/ Makes an HTTP call from a script — for fetching a token before the send, or chaining setup. **Off by default:** turn on **Allow pm.sendRequest** in the request's Settings tab, or pass `--allow-send-request` to [`kurlo run`](https://kurlo.dev/docs/guides/cli-runner/). Without it, the call throws and explains how to enable it. Both Postman's callback form and a direct return value work; the call is synchronous, so the callback runs immediately rather than on a later tick. ```js // Callback form — what imported Postman scripts use. pm.sendRequest({ method: "POST", url: "https://auth.example.com/token", header: { "Content-Type": "application/x-www-form-urlencoded" }, body: "grant_type=client_credentials", }, (err, res) => { if (err) throw err pm.request.headers.set("Authorization", "Bearer " + res.json().access_token) }) // Return-value form. const res = pm.sendRequest("https://api.example.com/health") pm.test("dependency is up", () => pm.expect(res.code).to.equal(200)) ``` Options follow Postman's request format: | Option | Accepted forms | |---|---| | `url` | A string, or an object with `raw` | | `header` (or `headers`) | An object, an array of `{ key, value, disabled }`, an array of `"Name: value"` strings, or one `"Name: value"` string with one header per line. Disabled entries are skipped. | | `body` | A string, or `{ mode, … }` with `raw`, `urlencoded`, `formdata` or `graphql`. A plain object is sent as JSON. | Kurlo sets `Content-Type` from the body when you do not set it yourself: | Body | `Content-Type` | |---|---| | `{ mode: "raw", options: { raw: { language: "json" } } }` | `application/json` (`xml`, `html`, `javascript` and `text` map the same way) | | `{ mode: "urlencoded", urlencoded: [{ key, value }] }` | `application/x-www-form-urlencoded`; the fields are URL-encoded | | `{ mode: "formdata", formdata: [{ key, value }] }` | `multipart/form-data` with a generated boundary, always; text fields only | | `{ mode: "graphql", graphql: { query, variables } }` | `application/json` | | A plain object | `application/json` | ```js pm.sendRequest({ url: "https://auth.example.com/token", method: "POST", body: { mode: "urlencoded", urlencoded: [ { key: "grant_type", value: "password" }, { key: "username", value: pm.environment.get("user") }, ], }, }, (err, res) => pm.environment.set("token", res.json().access_token)) ``` The response object mirrors `pm.response`: `.code`, `.status`, `.responseTime`, `.size`, `.text()`, `.json()`, `.headers.get(name)`, and `.to` for assertions. Limits and deliberate omissions: - 30 second timeout, 8 MB response cap, at most 5 redirects. - The call does **not** inherit the parent request's auth or cookie jar, and does not run scripts of its own. It does use the request's transport settings: proxy, TLS verification, and client certificate. Anything more would be a hidden second request carrying your credentials. - A non-2xx status is a normal response, not an error; only a transport failure produces one. - File bodies (`mode: "file"`) and file fields in `formdata` are not supported; the call throws and says so. ## Script timeout A script is capped at **2000 ms** by default. Raise it per request with **Script timeout** in the Settings tab, or for a whole run with `kurlo run --script-timeout`. The ceiling is 60000 ms, so a runaway loop can never wedge a send or a CI job. The same cap bounds a [`pm.sendRequest`](https://kurlo.dev/docs/reference/scripting-api/send-request/) call: a call that would run past the script deadline is canceled at that deadline. ## `pm.iterationData` | Method | Description | |--------|-------------| | `.get(key)` | Read the current data-row value for `key` (read-only) | During a data-driven run — the [Collection Runner](https://kurlo.dev/docs/guides/collection-runner/) with a data file, or [`kurlo run --data`](https://kurlo.dev/docs/guides/cli-runner/data/#data-driven-runs) — `pm.iterationData` exposes the current row. It's read-only; outside a data run every key is `undefined`. ```js pm.test("greets the row's user", () => { const body = pm.response.json() pm.expect(body.name).to.equal(pm.iterationData.get("name")) }) ``` # Assertions Source: https://kurlo.dev/docs/reference/scripting-api/assertions/ JavaScript: ```js pm.test("status is 200", () => pm.response.to.have.status(200)) pm.test("has id", () => pm.expect(pm.response.json()).to.have.property("id")) ``` Tengo: ```js body := pm.response.json() pm.test("status is 200", pm.response.code == 200) pm.test("has id", pm.expect(body).has_key("id")) ``` **`pm.test(name, fnOrResult)`** — register a named assertion. JavaScript accepts a callback or boolean. Tengo accepts a boolean expression. **`pm.expect(value)`** — chainable assertion builder. | Chain | Description | |-------|-------------| | `.equal(v)` | Strict equality | | `.not_equal(v)` | Inverse of `equal` | | `.contains(s)` | Substring or array membership | | `.exists()` | Not null/undefined | | `.is_null()` | Strict null check | | `.greater_than(n)` | `value > n` | | `.less_than(n)` | `value < n` | | `.has_key(k)` | Map contains key | | `.type_of()` | Returns the type as a string (`"string"`, `"int"`, `"map"`, etc.) | JavaScript also supports Chai-style aliases for the common Postman patterns: | Chain | Description | |-------|-------------| | `.to.equal(v)` | Strict equality | | `.to.include(v)` | Substring or array membership | | `.to.have.property(k)` | Object has property | | `.to.have.all.keys(...k)` | Object has exactly these keys; `.keys` alone means the same | | `.to.have.any.keys(...k)` | Object has at least one of these keys | | `.to.be.above(n)` | `value > n` | | `.to.be.below(n)` | `value < n` | | `pm.response.to.have.status(code)` | Response status code check | | `pm.response.to.have.header(name)` | Response carries the header | | `pm.response.to.have.jsonBody(path?, value?)` | Body is JSON; optionally check a dotted path, optionally its value | | `pm.response.to.have.jsonSchema(schema)` | Body matches a JSON Schema | ## JSON Schema `jsonSchema` validates against a draft-07 subset: `type`, `required`, `properties`, `patternProperties`, `additionalProperties`, `items`, `additionalItems`, `enum`, `const`, `minimum`/`maximum`/`exclusiveMinimum`/`exclusiveMaximum`/`multipleOf`, `minLength`/`maxLength`/`pattern`, `minItems`/`maxItems`/`uniqueItems`, `minProperties`/`maxProperties`, `allOf`/`anyOf`/`oneOf`/`not`, OpenAPI's `nullable`, and local `$ref` (`#/definitions/…`, `#/$defs/…`). Not implemented: remote `$ref` (the sandbox has no network) and `format` assertions — Ajv does not check formats by default either. ```js const schema = { type: "object", required: ["id", "name"], properties: { id: { type: "integer", minimum: 1 }, name: { type: "string" } } } pm.test("body matches the schema", () => pm.response.to.have.jsonSchema(schema)) ``` A failure names the path and the reason, for example `/items/1: missing required property "sku"`. # Bundled modules and compatibility Source: https://kurlo.dev/docs/reference/scripting-api/compatibility/ ## `require` JavaScript scripts can `require` a small set of stand-ins so imported Postman collections keep working. These are Kurlo implementations, not the npm packages. | Module | What you get | |--------|--------------| | `lodash` (also `underscore`) | The common collection/object helpers: `get`, `set`, `has`, `pick`, `omit`, `merge`, `cloneDeep`, `map`, `filter`, `find`, `reduce`, `uniq`/`uniqBy`, `groupBy`, `keyBy`, `countBy`, `sortBy`, `chunk`, `flatten`/`flattenDeep`, `difference`, `intersection`, `sum`/`sumBy`, `maxBy`/`minBy`, `range`, `times`, `isEmpty`/`isEqual`/`isNil`, and friends | | `ajv` | Constructor with `validate(schema, data)`, `compile(schema)`, `errors`, and `errorsText()` | | `tv4` | `validate(data, schema)`, `validateResult`, `validateMultiple`, `error` | | `uuid` | `v4()`, `validate(value)` | | `crypto-js` | The same shim exposed as the `CryptoJS` global | | `chai` | `{ expect }` | `_`, `tv4`, `Ajv`, `atob`, and `btoa` are also available as globals, and a script may shadow any of them (`const _ = require("lodash")` works). Anything outside that list fails with a message naming what was asked for — including an unsupported lodash member, so a missing helper surfaces as `lodash.debounce is not available in Kurlo's script sandbox` rather than a confusing `undefined is not a function`. ## Postman legacy globals JavaScript scripts written for Postman's older API run unchanged: | Name | Meaning | |------|---------| | `tests["name"] = condition` | Records a test that passes when the value is truthy, alongside `pm.test` results | | `responseBody`, `responseCode.code`, `responseHeaders`, `responseTime` | The response, in test scripts | | `postman.setEnvironmentVariable` / `getEnvironmentVariable` / `clearEnvironmentVariable` | Same as `pm.environment` | | `postman.setGlobalVariable` / `getGlobalVariable` / `clearGlobalVariable` | Same as `pm.globals` | | `postman.getResponseHeader(name)` | Same as `pm.response.headers.get(name)` | | `xml2Json(xml)` | Parses XML into an object: attributes under `$`, text beside child elements under `_`, repeated elements as arrays; `null` when the input is not XML | `postman.setNextRequest` throws, because the Collection Runner always runs requests in their declared order. ## JetBrains HTTP Client globals Scripts imported from `.http` files, written for the JetBrains HTTP Client, run in the JavaScript engine as well: | Name | Meaning | |------|---------| | `client.global.set` / `get` / `clear` / `clearAll` / `isEmpty` | Same as `pm.globals`; `get` returns `null` for a missing name | | `client.test(name, fn)` | Same as `pm.test` | | `client.assert(condition, message)` | Throws `message` when the condition is false | | `client.log(...values)` | Same as `pm.log` | | `request.variables.set` / `get` | Same as `pm.variables` | | `request.environment.get(name)` | Same as `pm.environment.get` | | `request.method`, `request.url.getRaw()`, `request.url.tryGetSubstituted()` | The request being sent | | `request.headers.findByName(name)` | A header with `getRawValue()` and `tryGetSubstituted()`, or `null` | | `response.status`, `response.body` | The status code and the body, parsed when it is JSON, in post-response scripts | | `response.headers.valueOf(name)` / `valuesOf(name)` | A response header | | `response.contentType.mimeType` / `charset` | The parsed `Content-Type` header | A script may declare its own `client`, `request` or `response` (`const response = pm.response.json()` works). `client.exit()` throws, because Kurlo cannot stop a script part-way. # Logging and engine notes Source: https://kurlo.dev/docs/reference/scripting-api/logging/ ## Logging **`pm.log(...values)`** — prints to the Scripts panel. Accepts any number of arguments, joined with spaces. Useful for debugging — the panel clears on each send. `console.log`, `console.info` and `console.debug` print the same way. `console.warn` lines are shown in amber and `console.error` lines in red, and `kurlo run` prints them with a `[warn]` or `[error]` prefix. Every [`pm.sendRequest`](https://kurlo.dev/docs/reference/scripting-api/send-request/) call adds a line of its own: the method, URL, status and time, or the reason it failed. A 4xx or 5xx answer is shown as a warning, so a rejected token call is visible without logging it yourself. When a script throws, the response shows a red banner with the error above the body, and the **Scripts** tab shows how many errors there were. **Open Scripts** in the banner jumps to the full output. A failing pre-request script stops the send; the output then appears under **Could not send request**, and so it does after a network error. Each script keeps its first 200 log lines; when it prints more, the last line says how many were left out. A line longer than 600 characters or 8 lines shows a preview with **Show all** and its size, so a logged response body does not fill the panel. Line breaks are kept, so `JSON.stringify(value, null, 2)` prints indented. ## Engine notes - JavaScript is the default engine for new requests and Postman-style scripts. - Tengo is kept for older requests and teams that already wrote Tengo snippets. - Both engines use the same variable/environment mutation contract. - Both engines block module imports and host APIs; only the [bundled `require` stand-ins](https://kurlo.dev/docs/reference/scripting-api/compatibility/#require) resolve. Use `pm.sendRequest`, Kurlo requests, and the Collection Runner for chained HTTP calls. ```js // blocked in JavaScript require("fs") import("node:fs") // blocked in Tengo json := import("json") ``` # Kurlo YAML format Source: https://kurlo.dev/docs/reference/kurlo-yaml-format/ > Public contract for Git-backed Kurlo workspaces. Kurlo stores Git-backed workspaces as plain YAML files. This format reference is intended for review tools, formatters, generators, and import/export integrations. Schema: `schemas/kurlo-workspace-yaml-v1.schema.json` ## Contract | Field | Value | |-------|-------| | Storage kind | `workspace-yaml` | | Format | `kurlo.workspace.yaml.v1` | | File version | `1` | | Path layout | `yaml-filesystem-names.v1` | | Encoding | UTF-8 YAML | Kurlo preserves unknown fields inside workspace, collection, request, environment, auth, settings, and row objects when it can. Tools should do the same to stay forward-compatible. # Directory layout and root index Source: https://kurlo.dev/docs/reference/kurlo-yaml-format/layout/ ## Directory layout ```text kurlo.yml workspaces/ / workspace.yml README.md collections/ / collection.yml requests/ .yml examples/ / .yml loadtests/ .yml environments/ .yml ``` `filesystemName` is the path segment of an object: its folder or file name. It is not written inside the YAML; readers take it from the path. Kurlo derives it from the object's name: spaces become `-`, Cyrillic is transliterated (`Общий` → `Obshchiy`), accents are dropped, and anything else outside `a-z A-Z 0-9 . _ -` becomes `-`. Two objects with the same name in one folder get `-1`, `-2` suffixes, compared without regard to case so the layout also works on macOS and Windows. Kurlo keeps every path in line with its name. When it saves, any file or folder whose path no longer matches the name, whether the object was renamed in the app, by editing the YAML, or in a pulled commit, is moved; Git shows it as a rename. Loading never moves anything, and nothing moves while the workspace has a file Kurlo cannot read. Request and environment files may include a top-level `order` for older exports. Newer writers should prefer `requestOrder`, `collectionOrder`, and `workspaceOrder`; readers must tolerate files without `order`. ## Root index `kurlo.yml` identifies the shared workspace store and records workspace order. ```yaml version: 1 format: kurlo.workspace.yaml.v1 workspaceOrder: - workspace-main ``` # Workspace file Source: https://kurlo.dev/docs/reference/kurlo-yaml-format/workspace/ Path: `workspaces//workspace.yml` ```yaml version: 1 workspace: id: workspace-main name: Main collectionOrder: - collection-core ``` The workspace README lives next to it in `workspaces//README.md` as plain UTF-8 Markdown; the name is matched in any letter case. Kurlo writes the file only when the README has text, ends it with a newline, keeps its CRLF line endings and byte order mark if it had them, and removes it when the README is cleared. A README over 256 KB, not UTF-8, or a symbolic link is left untouched. Older files that keep the text in `workspace.description` still load; Kurlo moves it into `README.md` on the next save. # Collection file Source: https://kurlo.dev/docs/reference/kurlo-yaml-format/collection/ Path: `workspaces//collections//collection.yml` ```yaml version: 1 collection: id: collection-core workspaceId: workspace-main name: Core API description: "" collapsed: false folderPaths: - - Auth - - Auth - Admin environmentIds: - env-core-dev - env-core-staging defaultEnvironmentId: env-core-staging folderDefaults: - id: folder-admin path: - Auth - Admin headers: - key: X-Admin value: "1" enabled: true auth: type: bearer bearerToken: '{{kurloSecret:collection.collection-core.folder.folder-admin.auth.bearerToken}}' requestOrder: - req-login ``` `collection.folderPaths` preserves explicit folders, including empty folders. `collection.folderDefaults` holds the headers, auth, `preRequestScript`/`testScript` (and their `Js` variants) a folder applies to its requests, keyed by `path`. An `auth.type` of `none` means the folder's requests send no auth; a missing `auth` means they inherit. Secret auth fields and secret header values become placeholders, as in collection defaults. Request files stay flat under `requests/`; the UI hierarchy comes from `request.folderPath` and `collection.folderPaths`, not from nested filesystem directories. `collection.environmentIds` lists the ids of workspace environments pinned to the collection, and `collection.defaultEnvironmentId` names the one selected when the collection is opened (the first pinned one if it is missing). Both are left out when nothing is pinned. Ids of environments that no longer exist are ignored. They only affect the app's environment switcher. ## OpenAPI source A collection kept in sync with an OpenAPI spec has an `openapi` block: ```yaml collection: openapi: source: https://api.example.com/openapi.json headers: - key: Authorization value: Bearer {{specToken}} enabled: true intervalMinutes: 15 skipTlsVerification: false ignored: - DELETE /legacy/{id} ``` `source` is a URL or a file path relative to the workspace folder, and may use `{{variables}}`, as may `headers`. `intervalMinutes` is how often the app checks while it is open; `0` means only by hand. `ignored` lists operations you chose not to add, so they are not offered again. The spec from the last applied sync is stored next to `collection.yml` as `openapi/spec.json`: commit it with the collection, because it is the base the next sync compares against. See [OpenAPI sync](https://kurlo.dev/docs/guides/openapi-sync/). # Request file Source: https://kurlo.dev/docs/reference/kurlo-yaml-format/request/ Path: `workspaces//collections//requests/.yml` ```yaml version: 1 request: id: req-login name: Login requestType: http collectionId: collection-core folderPath: - Auth method: POST url: "{{baseUrl}}/login" requestTab: body params: [] headers: - id: 1 enabled: true key: Content-Type value: application/json description: "" auth: type: bearer bearerToken: "{{kurloSecret:request:req-login:auth:bearerToken}}" basicUser: "" basicPass: "" apiKeyName: X-API-Key apiKeyValue: "" apiKeyIn: header oauth2GrantType: client_credentials oauth2AuthURL: "" oauth2TokenURL: "" oauth2ClientID: "" oauth2Secret: "" oauth2Scope: "" oauth2Token: "" oauth2RefreshToken: "" oauth2TokenExpiry: 0 oauth2UsePKCE: true awsAccessKey: "" awsSecretKey: "" awsRegion: us-east-1 awsService: execute-api bodyType: json rawBodyType: json bodyContent: |- {"username":"ada"} bodyFilePath: "" bodyFileName: "" formRows: [] graphqlSchema: "" preRequestScript: "" preRequestScriptJs: "" testScript: "" testScriptJs: "" requestNotes: "" settings: httpVersion: auto enableSSLVerification: true followRedirects: true followOriginalMethod: false followAuthorizationHeader: false removeRefererHeader: false encodeUrlAutomatically: true disableCookieJar: false maxRedirects: 10 timeoutMs: 30000 proxyUrl: "" browserEmulation: false browserOrigin: "" browserWithCredentials: false browserEnforceCORS: false browserEnforceCSP: false browserCSP: "" wsHandshakeTimeoutMs: 0 wsReconnectAttempts: 0 wsReconnectIntervalMs: 5000 wsMaxMessageSizeMb: 10 sioClientVersion: v3 sioPath: /socket.io sioNamespace: / grpcUseTls: false grpcUseReflection: true grpcServerName: "" grpcIncludeDefaultValues: true grpcMaxResponseMessageSizeMb: 10 settingsOverrides: {} grpcMethod: "" grpcMetadata: [] grpcUseReflection: true grpcProtoFilePath: "" grpcProtoFileName: "" grpcProtoImportPaths: [] ``` # Request fields Source: https://kurlo.dev/docs/reference/kurlo-yaml-format/request-fields/ | Field | Contract | |-------|----------| | `requestType` | `http`, `graphql`, `ws`, `socketio`, `grpc`, `mcp`, or `ai` | | `method` | `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`, or `SSE` | | `folderPath` | Display names only. Request files are stored flat; `folderPath` is the UI source of truth. | | `params`, `pathParams`, `vars`, `postResponseVars`, `headers`, `formRows`, `sioEvents`, `grpcMetadata` | Arrays of row objects: `id`, `enabled`, `key`, `value`, `description`, optional `secret`, `isFile`, `fileName`. A row with `secret: true` keeps its value in the encrypted local store, with a `{{kurloSecret:...}}` placeholder in the file. | | `vars` | [Request variables](https://kurlo.dev/docs/guides/environments/request-variables/) set before the send, as rows. They win over environment, collection and global values. Omitted when empty. | | `postResponseVars` | Post-response variables, as rows whose `value` is a JavaScript expression over `res`, such as `res.body.token`. HTTP and GraphQL only. Omitted when empty. | | `pathParams` | Values of the `:name` path variables in `url`. The names come from the URL; a row whose name the URL no longer has is dropped. | | `savedMessages` | WebSocket and Socket.IO only. Messages kept in the **Saved** menu, each with a `name`. A WebSocket message has `content` and `bodyType` (`text`, the default, `json`, `html`, `xml` or `binary`); a Socket.IO message has `event`, `args` (the same shape as `sioArgs`) and `ack: true` when it waits for an acknowledgement. Omitted when empty. | | `mcpMethod`, `mcpName`, `mcpArguments` | The MCP call: the method (`tools/list`, `tools/call` and the like), the tool, resource or prompt name, and the arguments as JSON text. | | `mcpProtocolVersion` | Pins an MCP protocol revision, such as `2025-06-18`. Empty lets Kurlo find the one the server speaks. | | `grpcMethod`, `grpcUseReflection`, `grpcProtoFilePath`, `grpcProtoFileName`, `grpcProtoImportPaths` | gRPC method and service-definition source metadata. | | `aiProvider` | `openai` (Chat Completions, also for OpenAI-compatible servers), `anthropic` (Messages), or `kurlo` (the default connection in Settings → AI on the machine that sends; `url` is empty). Otherwise `url` is the provider's base URL. | | `aiModel`, `aiSystem`, `aiPrompt` | Model ID, system prompt (up to 50,000 characters) and prompt (up to 200,000); all accept `{{variables}}`. | | `aiTemperature`, `aiTopP`, `aiMaxTokens`, `aiMaxSteps`, `aiIdleTimeoutSec` | Strings; empty means the default: the provider's, 8 steps for `aiMaxSteps`, 300 seconds of silence for `aiIdleTimeoutSec`. | | `aiThinking` | Empty, or `summarized` to show an Anthropic model's thinking. | | `aiStream` | `false` to wait for the whole answer; omitted when `true`. | | `aiToolRequestIds` | IDs of saved MCP requests whose tools the model may call. | | `aiKurloTools` | `true` to give the model Kurlo's read and run tools for the workspace; omitted when `false`. | | `aiConnectionId` | With `aiProvider: kurlo`, the id of the AI connection from Settings → AI to use; omitted for the default connection. | | `bodyType` | `none`, `json`, `text`, `xml`, `html`, `form`, `urlencoded`, `binary`, or `graphql`. | | `rawBodyType` | `text`, `json`, `html`, or `xml`. | | `preRequestScript`, `testScript` | Legacy Tengo scripts. | | `preRequestScriptJs`, `testScriptJs` | JavaScript pre-request/test scripts. | | `assertions` | HTTP and GraphQL only. A list of [assertions](https://kurlo.dev/docs/guides/scripting/assertions/), each with `enabled`, `target` (`status`, `responseTime`, `size`, `header.`, `body`, `body.` or `$.`), `operator` (`eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `notIn`, `contains`, `notContains`, `matches`, `exists`, `notExists`, `type`, `length`) and `value`, a string. Rows without a target are dropped on save. | | `auth.type` | `inherit`, `none`, `bearer`, `basic`, `apikey`, `jwt`, `oauth1`, `oauth2`, `aws`, `digest`, or `ntlm`. NTLM uses `basicUser` and `basicPass`. | | `auth.jwtAlgorithm`, `auth.jwtSecretBase64`, `auth.jwtPayload`, `auth.jwtHeaders`, `auth.jwtExpiresIn`, `auth.jwtAddTo`, `auth.jwtHeaderPrefix`, `auth.jwtQueryParam` | JWT Bearer settings. `jwtAlgorithm` is `HS256` (default), `HS384`, `HS512`, `RS256`, `RS384`, `RS512`, `PS256`, `PS384`, `PS512`, `ES256`, `ES384` or `ES512`. `jwtPayload` and `jwtHeaders` are JSON objects written as strings. `jwtExpiresIn` is a number of seconds as a string and adds `iat` and `exp`. `jwtAddTo` is `header` (default) or `query`; `jwtHeaderPrefix` defaults to `Bearer` and `jwtQueryParam` to `token`. Defaults are left out of the file, so `auth: { type: jwt }` with nothing else is valid. The token is signed on every send and never stored. | | `auth.oauth1ConsumerKey`, `auth.oauth1SignatureMethod`, `auth.oauth1AddTo`, `auth.oauth1Realm`, `auth.oauth1Callback`, `auth.oauth1Verifier`, `auth.oauth1Version`, `auth.oauth1Timestamp`, `auth.oauth1Nonce`, `auth.oauth1IncludeBodyHash`, `auth.oauth1AddEmptyParams` | OAuth 1.0 settings. `oauth1SignatureMethod` is `HMAC-SHA1` (default), `HMAC-SHA256`, `HMAC-SHA512`, `RSA-SHA1`, `RSA-SHA256`, `RSA-SHA512` or `PLAINTEXT`; `oauth1AddTo` is `header` (default), `query` or `body`. An empty timestamp or nonce is generated on every send. | | `auth.oauth2GrantType`, `auth.oauth2AuthURL`, `auth.oauth2TokenURL`, `auth.oauth2ClientID`, `auth.oauth2Scope`, `auth.oauth2TokenExpiry`, `auth.oauth2UsePKCE` | OAuth 2.0 grant metadata. `oauth2GrantType` is `client_credentials`, `authorization_code`, `password`, or `device_code`. Authorization Code can use PKCE. | | `openapi` | The OpenAPI operation this request was imported from, as the method and path template, for example `GET /users/{id}`. [OpenAPI sync](https://kurlo.dev/docs/guides/openapi-sync/) uses it to match the request to the spec. Left out for requests that are not linked. | | `settings` | Request transport settings. Unknown settings must be preserved by third-party tools. | | `settingsOverrides` | Per-request override markers for inherited collection defaults. | Secret-bearing auth fields (`bearerToken`, `basicPass`, `apiKeyValue`, `oauth2Secret`, `oauth2Token`, `oauth2RefreshToken`, `awsAccessKey`, `awsSecretKey`, `oauth1ConsumerSecret`, `oauth1Token`, `oauth1TokenSecret`, `oauth1PrivateKey`, `jwtSecret`, and `jwtPrivateKey`) are replaced with `{{kurloSecret:...}}` placeholders in shared Git/YAML workspaces. Their plaintext values stay in Kurlo's encrypted local profile A value that is only a variable reference, such as `{{apiToken}}`, holds no secret and is written as is. # Example file Source: https://kurlo.dev/docs/reference/kurlo-yaml-format/example/ Path: `workspaces//collections//examples//.yml` An example is a saved response together with the request snapshot that produced it. Examples sit in a directory beside `requests/`, not inside it: readers walk `requests/` recursively, so a `.yml` file anywhere under that tree is a request. ```yaml version: 1 order: 0 example: id: ex-created requestId: req-create-order name: Created source: captured snapshot: method: POST url: "{{baseUrl}}/orders" bodyType: json bodyContent: | {"amount": 500} response: statusCode: 201 status: 201 Created bodyMediaType: application/json body: |- { "id": "ord_1" } headers: - id: 1 enabled: true key: Content-Type value: application/json match: pathTemplate: /orders ``` The response body is stored in `response.body`, byte for byte. A multi-line body is written as a YAML block, so a JSON or XML body still diffs line by line. A body the YAML block form cannot hold exactly, for example one with Windows line endings or trailing spaces, is written as a quoted string instead. Older workspaces kept the body in a sibling file named by `response.bodyFile`. Readers still load that file, and Kurlo moves the body into `response.body` and removes the file on the next save. `bodyFile` must be a plain file name; a reader must refuse a value containing a path separator. `match` records how a mock server would select the example. It is written from the start so that serving examples later needs no change to stored workspaces. Examples are optional. A workspace written before they existed has no `examples/` directory, and readers must treat that as "no examples" rather than an error. # Load test file Source: https://kurlo.dev/docs/reference/kurlo-yaml-format/load-test/ Path: `workspaces//collections//loadtests/.yml` A load test is a flow of requests from the same collection plus the load to put on it and the criteria for passing. Each load test is one file; `order` keeps the order of load tests within the collection. ```yaml version: 1 order: 0 loadTest: id: lt-checkout name: Checkout flow settings: environment: staging thresholds: - metric: http_req_duration stat: p(95) op: < value: 300 - metric: http_req_duration stat: p(99) op: < value: 400 step: st-create - metric: http_req_failed stat: rate op: < value: 0.01 abortOnFail: true data: path: data/users.csv mode: per-vu scenarios: - id: sc-main name: Checkout executor: type: ramping-vus stages: - durationMs: 120000 target: 100 - durationMs: 600000 target: 100 - durationMs: 60000 target: 0 steps: - id: st-login requestId: req-login once: true extract: - var: token from: json path: $.access_token checks: - type: status value: "200" - id: st-create requestId: req-create-order name: create_order thinkTimeMs: 500 thinkJitterMs: 1000 checks: - type: jsonExists path: $.id ``` | Field | Meaning | |-------|---------| | `scenarios` | The flow. Kurlo uses exactly one scenario. | | `executor.type` | `constant-vus` (`vus`, `durationMs`), `ramping-vus` (`stages` of virtual users), `constant-arrival-rate` (`rate`, `durationMs`, `preAllocatedVUs`, `maxVUs`), `ramping-arrival-rate` (`stages` of iterations per time unit, `preAllocatedVUs`, `maxVUs`). `timeUnitMs` defaults to 1000. | | `steps[].requestId` | An HTTP or GraphQL request in the same collection. The step sends it with the collection's defaults, auth and the selected environment. | | `steps[].once` | Run the step once per virtual user, for example to log in. | | `steps[].extract` | Save a value from the response as a variable for later steps: `from: json` with a `$.` path, `from: header` with the header name, or `from: regex` with a pattern that has one `( )` group. | | `steps[].checks` | `status` (`value` is the expected code), `jsonExists` (`path`), `bodyContains` (`value`). A failed check does not stop the test. | | `steps[].thinkTimeMs`, `thinkJitterMs` | Wait after the step, plus a random extra wait up to `thinkJitterMs`. | | `thresholds` | `metric` is `http_req_duration` (stats `avg`, `min`, `med`, `max`, `p(90)`, `p(95)`, `p(99)`; `value` in milliseconds), `http_req_failed` or `checks` (stat `rate`; `value` from 0 to 1). `step` limits a threshold to one step by its id; `abortOnFail` stops the test when it fails. | | `data` | A CSV or JSON file relative to the workspace folder. `mode` is `per-vu`, `per-iteration` or `random`. | | `settings` | `environment` to run against, `insecure` to skip TLS certificate checks, `timeoutMs` per request. | Durations are in milliseconds. A load test holds no secrets: values such as passwords come from the environment when the test runs. Unlike other objects, a load test keeps only the fields listed here; Kurlo drops unknown fields on the next save. Load tests are optional, and a collection without a `loadtests/` directory has none. # Environment file Source: https://kurlo.dev/docs/reference/kurlo-yaml-format/environment/ Path: `workspaces//environments/.yml` ```yaml version: 1 environment: id: environment-local workspaceId: workspace-main name: Local values: - id: 1 enabled: true key: baseUrl value: https://api.example.test description: "" - id: 2 enabled: true key: token value: "{{kurloSecret:environment:environment-local:row:2}}" description: "" secret: true ``` `protected: true` on the environment marks it as one that AI agents connected through [`kurlo mcp`](https://kurlo.dev/docs/guides/mcp-server/permissions/#protected-environments) may not send requests with or change. It is left out when false. `color` is the environment's color in the app: `red`, `amber`, `green`, `blue` or `gray`. It is left out when the environment has none; any other value is ignored. # Secrets and Git behavior Source: https://kurlo.dev/docs/reference/kurlo-yaml-format/secrets/ ## Secrets Shared YAML files may contain placeholders in sensitive request auth fields and in rows marked `secret: true`. ```text {{kurloSecret:}} ``` Kurlo stores the actual values in its encrypted local `requests.json` profile. They are not part of the workspace directory or this shared public contract. Secret-aware tools should preserve placeholders as-is. If a tool cannot resolve a placeholder, it should keep the placeholder instead of replacing it with an empty string. ## Git behavior Kurlo treats these paths as managed Git content: - `kurlo.yml` - `.gitignore` - `workspaces/**/*.yml` Other files in the repository are intentionally left alone by commit, discard, stash, and conflict-resolution operations unless Kurlo explicitly adds support for them in a future format version. # App settings Source: https://kurlo.dev/docs/guides/settings/ > Configure saving, scripts, themes, proxying, shortcuts, updates, support, and local data handling. Open app settings from the gear at the bottom of the activity rail — the strip of icons on the far left — or with the **Settings** keyboard shortcut. Every page has the same layout: a title and a line on what it covers, then settings grouped in boxes, each row with its name and description on the left and its control on the right. The search field filters the settings navigation and the groups shown on the General page. App settings are different from the settings attached to API data: | Scope | Where to edit | What it affects | |-------|---------------|-----------------| | App | Activity rail -> gear | Kurlo on this device: saving mode, theme and zoom, global proxy, shortcuts, updates, and local preferences. | | Collection | Collection menu -> Settings | Defaults applied to requests in that collection. | | Request | Open request -> Settings tab | Transport and protocol behavior for one request. | See [Collection defaults](https://kurlo.dev/docs/guides/collection-defaults/) and [Per-request settings](https://kurlo.dev/docs/guides/request-settings/) for the other two scopes. # Saving Source: https://kurlo.dev/docs/guides/settings/saving/ Under **Editing**, the **Saving** row switches between two modes: - **Autosave** saves edits automatically. - **Manual save** keeps edits unsaved until you click **Save** or use the save shortcut. A dot on the request tab marks unsaved work. With autosave on, the number next to the **Saving** switch is the autosave delay: how long Kurlo waits after your last edit before it writes to disk, from 100 to 30,000 milliseconds. The default is 1,200. Every editor that autosaves uses it, and the setting is kept on this computer and in an all-data export. The mode covers every editor that has a **Save** button: requests, collection and folder settings, load tests, environments (name, **Inherits from** and variables), global variables and the workspace README. With manual save, nothing you type in them reaches the disk until you save, even when another action — switching the environment in use, creating an environment, renaming a collection — writes the workspace. Every one of them has the same two buttons in its header: the round arrow (**Revert**) throws the unsaved edits away, and **Save** turns into a dimmed **Saved** once there is nothing left to save. Quitting asks what to do with unsaved edits. Some things are saved right away in both modes, because they are actions rather than edits: creating, renaming from the sidebar, moving and deleting collections, folders and workspaces; **Protect from AI agents** and **Sandbox for the agent**; the environment in use; history, cookies and run results; and values that scripts write with `pm.environment.set(...)`, `pm.globals.set(...)` and similar calls. A value a script writes is saved on its own, without the unsaved edits next to it. In manual-save mode, an all-data export contains the last saved version of each request, not unsaved editor changes. Kurlo warns you before exporting when dirty requests exist. # Startup and tabs Source: https://kurlo.dev/docs/guides/settings/start-and-tabs/ ## Preview tabs Under **Editing**, enable **Preview tabs** to browse saved requests without accumulating tabs. Each newly opened request replaces the temporary tab, whose name is italic. Requests that already have an open tab switch to that tab. Double-click the temporary tab to keep it open. Editing or running its request also keeps the tab automatically, including active WebSocket, Socket.IO, SSE and gRPC requests. New unsaved requests always have their own tabs. The switch is off by default. Turning it on leaves existing tabs open; turning it off keeps the current preview as a regular tab. The preference and the preview tab are restored after a restart, and the preference is included in **Export all data**. ## On launch The **On launch** list chooses the screen Kurlo opens on; the row describes the current choice: | Option | What you see | |--------|--------------| | **Request editor** *(default)* | Your open tabs on the request editor. With no requests yet, a new unsaved HTTP request. | | **Where you left off** | The last screen of the previous session — Git, the runner, a collection, an environment or the overview. | | **Workspace overview** | Collections, recent history and storage for the active workspace. | Your open tabs come back in every mode; only the screen in front changes. A workspace that needs attention, such as a missing folder or broken YAML, opens where you can fix it whatever this is set to. # Script engine Source: https://kurlo.dev/docs/guides/settings/script-engine/ Under **Scripts**, choose **JavaScript** for Postman-style scripts or **Tengo** for the legacy lightweight engine. The selection controls which script fields Kurlo displays and runs. Each request and collection keeps separate JavaScript and Tengo source. Switching engines does not delete the script stored for the other engine. Imports from Postman, Insomnia, Bruno and other tools put their scripts in the JavaScript fields, and exports to those formats take the JavaScript scripts, whichever engine is selected. Tengo scripts stay in Kurlo. See [Scripting](https://kurlo.dev/docs/guides/scripting/) for runtime behavior and examples. # Default location and data Source: https://kurlo.dev/docs/guides/settings/storage/ ## Default location Under **Files**, type a path or click **Browse**; Kurlo saves it when you leave the field, press `Enter` or click **Save**. The default location is the starting directory for: - New folder-backed workspaces. - Collection exports that ask for a destination folder. Changing it does not move existing workspaces or repositories. ## Data **Export all data** creates a Kurlo-to-Kurlo JSON backup. **Import all data** replaces the current local profile after confirmation. Read [Backup & recovery](https://kurlo.dev/docs/guides/backup-recovery/) before using the import action. # Appearance Source: https://kurlo.dev/docs/guides/settings/appearance/ The **Mode** row chooses **Light**, **Dark**, or **System**, then select separate light and dark variants. Each variant is shown as a miniature of Kurlo in its own colours — sidebar, request bar, a table and a highlighted response — so you can compare them before switching. System mode follows the operating-system appearance and uses the matching selected variant. | Mode | Variants | |------|----------| | Light | Light, GitHub Light, JetBrains Light, VS Code Light Modern, Catppuccin Latte, Flexoki Paper, High Contrast Light | | Dark | Dark, GitHub Dark Dimmed, JetBrains Dark, VS Code Dark Modern, One Dark, Tokyo Night, Catppuccin Mocha, Nord, Everforest, High Contrast Dark | Every variant keeps text, method labels and status colours at a contrast ratio of at least 4.5:1; the two High Contrast variants raise text to 7:1 and draw stronger borders. Light Monochrome, Light Pastel, Dark Monochrome, Dark Pastel, Catppuccin Frappé and Catppuccin Macchiato were removed in favour of these: a saved choice moves to Light, Flexoki Paper, Dark, Everforest or Catppuccin Mocha. Theme preferences apply only to Kurlo's UI; they do not change generated code, request headers, or response rendering. The **Zoom** row makes the whole interface larger or smaller: **−** and **+** step from 80% to 150% and **Reset** returns to 100%. The same steps are on `Cmd/Ctrl =`, `Cmd/Ctrl -` and `Cmd/Ctrl 0`, in the command palette as **Zoom in**, **Zoom out** and **Reset zoom**, and on macOS in the **View** menu. The size is stored on this device. On Windows and Linux Kurlo draws its own title bar: drag the top bar to move the window, double-click it to maximize, and use the buttons on the right to minimize, maximize or close. The empty spot between the request tabs and the environment switcher always stays free to grab, however many tabs are open: the tabs scroll instead of filling it. On Linux `Ctrl Q` quits. # Proxy Source: https://kurlo.dev/docs/guides/settings/proxy/ The Proxy page configures the fallback used across requests on this device. Request and collection proxy URLs can override it. Choose **Off**, **On** or **System** in the first row; with **On**, the **Server** group (protocol, address and port, bypass list) and the **Authentication** group appear below. See [Proxy configuration](https://kurlo.dev/docs/guides/proxy/) for precedence, authentication, bypass rules, and the difference between Off, On, and System modes. # AI connections Source: https://kurlo.dev/docs/guides/settings/ai/ ## AI **Your agents** connects installed Codex and Claude Code CLIs using their own accounts. Each shows connection status, CLI version, model selection, and executable controls. Codex also shows reported plan limits when available. See [Local agents](https://kurlo.dev/docs/guides/agent/local-agents/) for sign-in and setup. **Kurlo agent** lists the model connections used by the built-in agent. An [AI request](https://kurlo.dev/docs/guides/request-types/ai/#ai) can use a Kurlo connection or its own provider URL and credentials. There are three ways to connect a model: - **OpenRouter.** Click **Connect OpenRouter**. Kurlo opens openrouter.ai in your browser, where Kurlo asks for a key labelled `Kurlo`. After you approve, the browser passes through kurlo.dev back to the Kurlo app on a one-time local address, and the key is saved. You pay OpenRouter directly and can use Claude, GPT, Gemini and other models with one account. Click **Reopen browser** if you closed the tab, or **Cancel** to stop. The sign-in expires after five minutes. - **Your API key.** Click **Add key**, choose Anthropic, OpenAI or OpenAI-compatible (enter its base URL, such as `https://llm.example.com/v1`), and paste the key. **Test** checks the key and loads the provider's models; choose one and click **Save**. - **Local model.** Click **Find local models**. Kurlo looks for Ollama on port 11434 and LM Studio on port 1234 on this machine and lists their models. For another OpenAI-compatible server, enter its URL and click **Check**. Nothing leaves your computer. Model lists open with a search field: type part of a name, use the arrow keys and press `Enter`. **Recommended** marks models that handle tool calls well, and **No tools** marks models whose provider reports no tool support. Kurlo keeps up to ten connections. The first one becomes the default; **Make default** changes it. The model next to a connection opens its model list, and **Remove** (click twice) deletes the connection and its key. An AI request whose provider is **Kurlo connection** uses the default connection, and the [agent](https://kurlo.dev/docs/guides/agent/) starts new chats with it. Keys are encrypted with the same key as the local profile, which Kurlo keeps in the system keychain, and are stored in `preferences.json`. They are never written to workspace YAML or shown in the interface: a connection shows only a hint such as `sk-ant-…XYZ`, and when a provider repeats the key in an error, Kurlo shows `[your key]` instead. Checking a key and listing models use the system proxy environment variables, not the proxy configured in Kurlo. # Shortcuts Source: https://kurlo.dev/docs/guides/settings/shortcuts/ Shortcuts are grouped by area. Click a combination and press the new one; the line under the title says what Kurlo is waiting for. Individual shortcuts and the complete set can be reset to their defaults. The current command list and default bindings are documented in [Keyboard shortcuts](https://kurlo.dev/docs/reference/keyboard-shortcuts/). # Updates and support Source: https://kurlo.dev/docs/guides/settings/updates/ ## Updates Updates live in the **About** tab, under the version. The first row shows the current state and one action: **Check for updates**, **Check again**, **Install** or **Download**, **Restart now**, or **Try again** after an error. When a new release is found, its notes appear below the list. When the background check finds a release, a notice in the lower-right corner says so; **View** opens the **About** tab. **Install updates automatically** installs a discovered release in the background, then asks you to restart. Development builds created with `make dev` or `go run` do not use the release updater, so both controls are off there. For a Windows MSIX installation, download and open the next `.msix` package to upgrade in place. The package directory is managed by Windows. ## What's new The first time Kurlo starts after updating to a new version, it opens a **What's new** screen with that release's notes. It appears once per version: relaunching the same build, downgrading, and a first-ever install all stay quiet — a brand-new user has nothing to catch up on. The first launch after updating from a 2.x version to 3.0 or later shows **Meet Agent mode** instead: the three agents you can use, with **Try Agent mode** to open the [Agent](https://kurlo.dev/docs/guides/agent/) tab and **All changes** for the release notes. **Later** closes it, and it does not come back. You can reopen it any time from **About → What's new**. The notes are bundled with the build, so the screen works offline and always describes the version you are actually running. ## Support and About **Support** links to the GitHub repository and to [Kurlo on Boosty](https://kurlo.dev/docs/support/), opens Kurlo's public issue tracker for bugs and questions, copies a diagnostics summary (version, platform, Git and storage state) to paste into an issue, and opens the folder holding `kurlo.log`. **About** shows the installed Kurlo version and platform; include both when reporting a problem. For common failures, start with [Troubleshooting](https://kurlo.dev/docs/troubleshooting/). # Keyboard shortcuts Source: https://kurlo.dev/docs/reference/keyboard-shortcuts/ > Look up default bindings and fixed gestures, and customize bindings in Settings → Shortcuts. On macOS Kurlo displays `Cmd` shortcuts with `⌘`. On Windows and Linux the same defaults display and run as `Ctrl`, with modifiers in the usual `Ctrl` → `Alt` → `Shift` order. Shortcuts follow the physical key, so they keep working on a Cyrillic, Greek or any other non-Latin layout. To change a binding listed in **Settings → Shortcuts**, click its chip and press the new combination. Use **Reset all** to restore the defaults. The [request editor shortcuts](https://kurlo.dev/docs/reference/keyboard-shortcuts/requests/) also list fixed actions such as sending with `Enter` in the URL field. Right-click any text field or code editor for **Cut**, **Copy**, **Paste** and **Select all**. The same actions keep their usual `Cmd/Ctrl X`, `C`, `V` and `A` keys, and a read-only editor such as the response body offers only **Copy** and **Select all**. # Global shortcuts Source: https://kurlo.dev/docs/reference/keyboard-shortcuts/global/ ## Global | Shortcut | Action | |----------|--------| | `Cmd/Ctrl K` | Command palette — search saved requests and agent chats, and run commands | | `Cmd/Ctrl ,` | Open settings | | `Alt Cmd/Ctrl P` | Toggle performance dock | | `Cmd/Ctrl Backslash` | Toggle sidebar | | `Alt Cmd/Ctrl Backslash` | Toggle right sidebar / code snippet panel | | `Cmd/Ctrl =` | Zoom in — make the whole interface larger | | `Cmd/Ctrl -` | Zoom out | | `Cmd/Ctrl 0` | Reset zoom to 100% | | `Cmd/Ctrl /` | Open shortcut help | | `Alt Cmd/Ctrl V` | Put the response beside or below the request | | `Alt Cmd/Ctrl 1` | Show collections in the sidebar | | `Alt Cmd/Ctrl 2` | Show environments in the sidebar | | `Alt Cmd/Ctrl 3` | Show history in the sidebar | | `Alt Cmd/Ctrl 4` | Show the agent | | `Alt Cmd/Ctrl E` | Choose the environment | | `Shift Cmd/Ctrl N` | New collection | | `Cmd/Ctrl O` | Import a collection | | `Shift Cmd/Ctrl R` | Open the collection runner for the current collection | # Request editor shortcuts Source: https://kurlo.dev/docs/reference/keyboard-shortcuts/requests/ ## Requests | Shortcut | Action | |----------|--------| | `Cmd/Ctrl N` | New HTTP request | | `Cmd/Ctrl L` | Focus the request URL | | `Cmd/Ctrl W` | Close current tab | | `Alt Cmd/Ctrl W` | Force close current tab | | `Alt Shift Cmd/Ctrl W` | Close the other tabs | | `Shift Cmd/Ctrl W` | Close all tabs | | `Shift Cmd/Ctrl T` | Reopen last closed tab | | `Cmd/Ctrl Enter` | Send request | | `Escape` | Cancel the request that is running | | `Cmd/Ctrl S` | Save request | | `Shift Cmd/Ctrl C` | Copy the request as cURL | | `Shift Cmd/Ctrl F` | Find and replace in the request's collection or folder | | `Cmd/Ctrl 1` … `Cmd/Ctrl 8` | Switch to tab 1–8 | | `Cmd/Ctrl 9` | Switch to the last tab, whichever number it is | | `Shift Cmd/Ctrl [` / `Shift Cmd/Ctrl ]` | Previous / next tab | `Escape` cancels only while the open request is running; otherwise it closes menus as before. Closing several tabs asks about unsaved changes and drafts one tab at a time, and stops if you cancel. The `Alt` shortcuts other than the tab ones leave text fields alone, so `AltGr` combinations still type characters such as `€` there. Two more work without a binding and cannot be remapped: `Enter` in the URL field sends the request — or connects a WebSocket, Socket.IO or SSE request — and a middle click on a tab closes it. # Sidebar shortcuts Source: https://kurlo.dev/docs/reference/keyboard-shortcuts/sidebar/ ## Sidebar | Shortcut | Action | |----------|--------| | `Cmd/Ctrl F` | Search sidebar | | `↑` / `↓` | Previous / next sidebar item | | `→` / `←` | Expand / collapse selected item | | `Alt →` / `Alt ←` | Expand all / collapse all | | `Cmd/Ctrl E` | Rename selected item | | `Cmd/Ctrl D` | Duplicate selected item | | `Cmd/Ctrl C` / `Cmd/Ctrl V` | Copy / paste selected item | | `Backspace` | Delete selected item | The arrow keys and `Backspace` leave the sidebar alone while a text field, the response body, a dialog, a menu or a tab bar has focus — there they scroll, edit or move between choices instead. # Agent shortcuts Source: https://kurlo.dev/docs/reference/keyboard-shortcuts/agent/ ## Agent | Shortcut | Action | |----------|--------| | `Enter` or `Cmd/Ctrl Enter` | Send the message | | `Shift Enter` | New line in the message | | `Cmd/Ctrl F` | Search chats | | `F2` | Rename the selected chat | | `Cmd/Ctrl W` | Close the Agent tab and keep its draft | | `Escape` | Close the agent picker, a menu or chat details | While the Agent tab is open, [request editor](https://kurlo.dev/docs/reference/keyboard-shortcuts/requests/) and [sidebar](https://kurlo.dev/docs/reference/keyboard-shortcuts/sidebar/) shortcuts such as Send, Copy as cURL, Find and replace, and Delete selection are disabled. Arrow keys scroll the chat. Tab, zoom, search, settings and **Show** shortcuts work everywhere. # Remapping Source: https://kurlo.dev/docs/reference/keyboard-shortcuts/remapping/ **Settings → Shortcuts** lists every action with its current binding. Click a shortcut, press the desired key combination, and the new binding is saved immediately. Assigning an existing combination unassigns it from the previous action. **Reset all** restores the default table. On Windows a binding can use the Windows key, and on Linux the Super key; they show as their own keys rather than as `Ctrl`. The send shortcut also sends the message from the WebSocket, Socket.IO and gRPC message editors, and a rebound send shortcut works there too. # Performance dock Source: https://kurlo.dev/docs/reference/performance/ > Inspect CPU usage, resident memory and the processes used by Kurlo. Click the gauge icon next to GitHub in the status bar, or press **Cmd/Ctrl Alt P**, to open the Performance dock. Use the same button or shortcut to close it. Kurlo remembers whether the dock was open and your selected view. Drag the upper edge to adjust its height. The dock can use up to half the window height and keeps room for the workspace above it. Its height is remembered when you reopen it. You can also focus the divider and use the Up/Down arrows, Home or End. The dock shows CPU usage, resident memory, uptime and process ID, with CPU and memory charts covering the last two minutes. Sampling runs once a second while the dock is open and pauses when the window is minimized. Closing the dock stops sampling. Reopening starts a new chart history. ## Choose a view - **All processes** sums CPU and memory across Kurlo's processes. Uptime and PID refer to the main application. - **Main** shows the Go application process. - **Webview** combines the webview processes used by the interface. - **Child** combines child processes, including MCP servers, agent command-line tools and k6 load tests. For a group, uptime shows the longest-running process. PID is shown only when the selected view contains one process. The process table always lists all detected application processes, regardless of the selected view. CPU usage is measured relative to one logical core, so a process using several cores can exceed 100%. Memory is resident memory (RSS), displayed in MB using 1 MB = 1,048,576 bytes. Summing RSS can count shared pages more than once. These values can differ from the memory figures shown by your system monitor. ## Unavailable metrics A dash (**—**) means the metric is unavailable. CPU usage needs two samples, so the first sample has no CPU value. A newly started process also needs a second sample. An empty process group shows dashes. Native sensors support macOS, Windows and Linux without installing another tool. On other platforms, or macOS builds without cgo, the dock identifies the main process and shows a limited-metrics notice. Operating-system permissions can also make individual metrics unavailable. # Performance fixtures Source: https://kurlo.dev/docs/reference/performance-fixtures/ > Reproducible large workspaces and responses for local performance checks. Kurlo includes a fixture generator for exercising the highest-risk UI and storage paths before a release: large sidebars, deep folder trees, request history, huge responses, and Git/YAML diagnostics. Generated files are written to `perf/fixtures/` and are ignored by Git because the default set can be hundreds of megabytes. ## Generate fixtures From the repository root: ```sh npm run perf:fixtures ``` For a faster smoke set: ```sh npm run perf:fixtures -- --requests 250 --folders 50 --history 500 --response-mb 2 ``` Useful options: | Option | Default | Meaning | |--------|---------|---------| | `--requests` | `5000` | Saved requests spread across collections and request types. | | `--folders` | `500` | Nested folder paths preserved in collections and YAML workspaces. | | `--history` | `10000` | Request history rows. | | `--response-mb` | `50` | Approximate size of `huge-response.json`. | | `--collections` | `5` | Collections in the generated workspace. | | `--out` | `perf/fixtures` | Output directory. | The YAML workspace is written by Kurlo's own Go writer (`TestPerfFixtureWorkspace` in `apps/desktop/internal/api`), so it always matches the current file format. Generation fails if the written workspace has diagnostics or if saving it again would change any file. Generating needs Go on the `PATH`. Run the generated data through the app UI (Playwright, Chromium and WebKit): ```bash cd apps/desktop/frontend KURLO_PERF_FIXTURES=$PWD/../../../perf/fixtures npx playwright test -g "perf fixtures" ``` It prints first paint, sidebar search, opening a request, the history view and loading the huge response, and fails when first paint takes over 10 s, search over 500 ms or opening a request over 400 ms. On an Apple M-series machine with the default set, opening a request takes about 130 ms and saving the open tabs about 10 ms. ## Outputs - `request-store-large.json` - all-data payload with workspaces, collections, folders, requests, environments, history, and cookies. - `huge-response.json` - large JSON response body for response viewer rendering, paging, and search. - `kurlo-yaml-large/` - Git/YAML workspace written by the Kurlo writer: collections, nested folders, requests with examples and setting overrides, an environment with a secret, and workspace cookies. - `manifest.json` - counts, generated paths, and suggested manual checks. ## P0 checks Use the fixtures to smoke-test these surfaces after storage, sidebar, import/export, or response-viewer changes: - Import `request-store-large.json` through the all-data import path. - Open collections and verify expand/collapse, nested folders, search, and starred rows remain responsive. - Open history and verify date collapse/search keep stable layout. - Load `huge-response.json` into the response viewer and check raw view, paging, and search. - Open `kurlo-yaml-large/` as a Git-backed workspace and confirm diagnostics stay clean. - Toggle autosave/manual-save and verify request and environment dirty states behave the same way on large data. # Troubleshooting Source: https://kurlo.dev/docs/troubleshooting/ > Common installation, network, and runtime problems — and how to fix them. This page collects the issues people run into most often. If your situation isn't listed, the fastest path is the [GitHub issue tracker](https://github.com/stormhop/kurlo/issues) — please include your Kurlo version (Settings → About), OS, and a reproduction. # Installation Source: https://kurlo.dev/docs/troubleshooting/installation/ ## macOS: "Kurlo Not Opened" or "Apple could not verify Kurlo" Current Kurlo DMGs are not Apple-notarized, so Gatekeeper blocks the first launch. On macOS 15 Sequoia and later the dialog only offers **Done** and **Move to Trash**, and right-click → **Open** no longer works. Pick one of these: 1. **System Settings.** Click **Done**, open *System Settings → Privacy & Security* and scroll down to *Security*. Next to "Kurlo was blocked to protect your Mac" click **Open Anyway**, confirm with your password, then click **Open Anyway** once more. From then on Kurlo opens normally. 2. **Terminal.** Remove the quarantine flag and launch as usual: ```bash xattr -dr com.apple.quarantine /Applications/Kurlo.app ``` On macOS 12–14 you can also right-click `Kurlo.app` in Finder → **Open**, then **Open** again in the dialog. ## macOS: "Kurlo is damaged and can't be opened" macOS shows this for quarantined apps that are not notarized, most often when the download came through a browser that re-tags files or through a package manager. The app is not broken. Run: ```bash xattr -dr com.apple.quarantine /Applications/Kurlo.app ``` then open from Finder normally. ## Windows: SmartScreen warning "Windows protected your PC" Confirm the installer or the portable app came from the official release repository and verify its SHA-256 checksum, then click **More info** → **Run anyway**. Neither the NSIS installer nor the portable `.exe` is currently Authenticode-signed. In-app updater binaries are separately verified by SHA-256 and minisign before installation. ## Linux: AppImage won't launch The most common cause is a missing executable bit: ```bash chmod +x kurlo-*.AppImage ./kurlo-*.AppImage ``` If you see `libfuse.so.2: cannot open shared object file`, install FUSE 2: ```bash sudo apt install libfuse2 # Debian/Ubuntu sudo dnf install fuse-libs # Fedora ``` ## Linux: GTK / WebKit errors An error such as `libwebkit2gtk-4.1.so.0: cannot open shared object file` means the GTK 3 or WebKitGTK 4.1 runtime is missing. Install it: ```bash # Debian / Ubuntu sudo apt install libgtk-3-0 libwebkit2gtk-4.1-0 # Fedora sudo dnf install gtk3 webkit2gtk4.1 ``` Kurlo 2.2.2 and earlier linked against WebKitGTK 4.0, which Ubuntu 24.04 and later no longer ship, so those versions fail on them with `libwebkit2gtk-4.0.so.37: cannot open shared object file`. Use a newer release. # Connectivity Source: https://kurlo.dev/docs/troubleshooting/connectivity/ ## "The request timed out" on every request Check, in order: 1. Can you `curl` the same URL from a terminal on the same machine? 2. Is your VPN / corporate proxy blocking it? See [Proxy setup](https://kurlo.dev/docs/troubleshooting/connectivity/#requests-go-through-a-corporate-proxy). 3. Open *Per-request settings* and bump the timeout to `60000` (60 s). Some upstream services are slow to respond on the first request. ## "TLS handshake failure" / "certificate signed by unknown authority" Most often a corporate root CA isn't trusted by your OS. Install the CA into your system trust store — Kurlo uses OS trust roots. After installing, restart Kurlo. If you can't install the CA system-wide, you can disable verification just for the offending request in *Per-request settings → Enable SSL certificate verification* (a confirmation dialog explains the risk). Don't ship a request with this off to a server you don't control. ## Requests go through a corporate proxy Open **Settings -> Proxy** and choose **System** to use standard environment proxy behavior: - `HTTP_PROXY` / `HTTPS_PROXY` - proxy URL, optionally with credentials. - `NO_PROXY` - comma-separated hosts that connect directly. Alternatively, choose **On** and configure an HTTP, HTTPS, or SOCKS5 proxy directly in Kurlo. A non-empty request or collection proxy URL overrides the global mode. See [Proxy configuration](https://kurlo.dev/docs/guides/proxy/) for precedence, bypass matching, password persistence, and direct connections. ## DNS resolution fails inside Kurlo but works in browser Check whether the browser and Kurlo are taking different proxy paths. In System mode, add the hostname to `NO_PROXY`. In custom On mode, add it to **Proxy Bypass**. Use a hostname only, without protocol or port. # Updates Source: https://kurlo.dev/docs/troubleshooting/updates/ ## "No compatible update package is available for this device yet" This error means the auto-updater couldn't find a binary for your platform in the latest release. Either: - A new platform was added in the latest release and your old build doesn't know about it (unlikely), - Or the release was partial — e.g. the maintainer published a macOS-only patch release. Wait for the next full release. ## Updates aren't available in development builds If you're running a `make dev` / `go run` build, Settings → About says *Development build* and explains why, instead of offering a check. This is intentional — there's no released version newer than your local source tree. Install a release build to receive updates. ## "The downloaded update could not be verified" The downloaded binary's SHA-256 or minisign signature didn't match what `latest.json` claimed. Causes: - Network interruption during download — try again. - Antivirus modified the binary in transit — temporarily allowlist the Kurlo update cache. - Compromised release channel — file a security issue immediately ([SECURITY.md](https://github.com/stormhop/kurlo/blob/main/SECURITY.md)). ## Linux: "Kurlo cannot replace its AppImage file in this folder" Kurlo updates an AppImage by replacing the `.AppImage` file it was started from, and the folder that holds it is read-only for your user, for example `/opt`. Move the AppImage to a folder you own, such as `~/Applications`, and install the update again. AppImages from Kurlo 2.2.3 and earlier cannot update themselves at all: download 2.2.4 or later from the [download page](https://kurlo.dev/download/) once. ## Update applied but Kurlo didn't restart Click *Restart now* in Settings → About. If that doesn't work, quit Kurlo manually and reopen it — the new binary is already in place. # Data and storage Source: https://kurlo.dev/docs/troubleshooting/storage/ ## My collections / environments are gone First, don't panic and don't reinstall — your data is on disk, not in the app bundle. Check whether: - You're in a different workspace than you remember. Switch via the workspace dropdown in the title bar. - You signed into a different OS user / Profile and Kurlo is reading another directory. Find your data manually: | Platform | Location | |----------|----------| | macOS | `~/Library/Application Support/Kurlo/` | | Windows | `%AppData%\Kurlo\` | | Linux | `~/.config/Kurlo/` | The `requests.json` file is an AES-256-GCM encrypted JSON envelope containing local profile state and secrets. If it's present but Kurlo can't read it, see "Decryption failed" below. ## "Decryption failed" or empty on startup Kurlo couldn't decrypt `requests.json` with any available key copy. Kurlo normally keeps `request-store.key` in the app-data directory as a `0600` recovery copy and also stores the key in Keychain, DPAPI, or libsecret when available. Common causes: - `requests.json` was restored without the matching `request-store.key`. - Files were copied from another OS user without preserving access to the key. - The encrypted profile and recovery key came from different installations. Restore `requests.json` and its matching `request-store.key` together. If no matching key exists, the encrypted data cannot be recovered; export/import backups are the safer migration path between machines. See [Backup & recovery](https://kurlo.dev/docs/guides/backup-recovery/) for the full restore procedure. ## "Warning: changes could not be saved" Disk full, or Kurlo's data directory is no longer writable (permissions changed, drive unmounted). Free up space or fix permissions and the next save will succeed. # Interface issues Source: https://kurlo.dev/docs/troubleshooting/ui/ ## UI quirks ### Settings → About says "DEV BUILD" but I downloaded a release Your build has `appVersion=dev` baked in — the release ldflags didn't apply. If you built it yourself, run `make build` from a tagged commit. If you downloaded it from GitHub releases, file an issue. ### Sidebar drag-and-drop doesn't work Drag-and-drop is disabled while the sidebar search has text in it (because the sorted order is by relevance, not user-defined). Clear the search box and drag works again. ### A folder won't accept any more requests Folders cap at 50 requests for performance. Either move some requests up to the parent collection, or split the folder into subfolders. # Performance Source: https://kurlo.dev/docs/troubleshooting/performance/ ## "App feels sluggish when typing in the URL" Open **Settings → General → Editing** and find the **Saving** row. With **Autosave** enabled, Kurlo saves after the configured delay, which defaults to 1,200 ms. If this interrupts editing, increase the delay or choose **Manual save**. Save edits with **Save** or `Cmd/Ctrl S`. To remove stored history, open **History** in the activity rail and choose **⋯ → Clear all**. This clears history across workspaces in the current profile. ## Huge response slows everything down Responses over 100 MB are truncated while being read; bytes beyond the cap are not kept in memory and cannot be recovered with **Save to file**. For very large downloads, use a dedicated download tool until Kurlo supports uncapped streaming-to-file. # Asking for help Source: https://kurlo.dev/docs/troubleshooting/support/ If you're stuck, the fastest path is: 1. Open *Settings → About* and note your version + platform. 2. Open the browser DevTools inside Kurlo (right-click → *Inspect Element* in dev/source builds, or run with `KURLO_DEVTOOLS=1` if your build supports it) and copy any console errors. 3. File a [GitHub issue](https://github.com/stormhop/kurlo/issues/new) with the version, platform, console output, and a reproduction. For security issues, please use [SECURITY.md](https://github.com/stormhop/kurlo/blob/main/SECURITY.md) instead of public issues. # FAQ Source: https://kurlo.dev/docs/faq/ > Find answers about data storage, backups, installation, auto-updates, and Postman compatibility. ## Is Kurlo free? Yes — free and open source under the [MIT license](https://github.com/stormhop/kurlo/blob/main/LICENSE), on macOS, Windows, and Linux. The full desktop application source is at [stormhop/kurlo](https://github.com/stormhop/kurlo), which is also where releases are published. You can read it, [build it yourself](https://github.com/stormhop/kurlo#building-from-source), or [contribute](https://github.com/stormhop/kurlo/blob/main/CONTRIBUTING.md). ## Is my data sent anywhere? Kurlo is local-first: requests, collections, history, environments, and secrets live on disk. There is no account system, Kurlo cloud sync, analytics, or telemetry. Network traffic still occurs for actions that inherently need it: requests and realtime connections you start, OAuth authorization/token calls, GraphQL introspection, Git fetch/pull/push/clone operations, and release update checks. ## Where is my data stored? | Platform | Path | |----------|------| | macOS | `~/Library/Application Support/Kurlo/` | | Windows | `%APPDATA%\Kurlo\` | | Linux | `~/.config/Kurlo/` | The local profile is an AES-256-GCM encrypted JSON envelope stored as `requests.json`, not SQLite. Kurlo also writes `request-store.key` as a `0600` recovery copy of the encryption key. Where available, the same key is additionally stored in macOS Keychain, Windows DPAPI, or Linux libsecret. Folder/Git workspace YAML is intentionally readable so it can be reviewed and committed. Sensitive values are replaced by `{{kurloSecret:...}}` placeholders and retained in the encrypted local profile. ## How do I export and back up my data? Use **Settings → General → Data → Export all data** for a portable Kurlo backup. It includes profile data, history, cookies, and selected preferences. The plaintext file can contain secrets. Collection exports are for interoperability and do not include runtime history or cookies. For an exact disk-level backup, quit Kurlo and copy the data directory with both `requests.json` and its matching `request-store.key`. Back up external workspace repositories separately. See [Backup & recovery](https://kurlo.dev/docs/guides/backup-recovery/) for contents, exclusions, migration, and destructive restore behavior. ## macOS says "the app can't be opened" If macOS reports the app is damaged after download, the file likely got the quarantine attribute from a non-standard download path. Run: ```sh xattr -d com.apple.quarantine /Applications/Kurlo.app ``` If that doesn't help, redownload from the [official releases page](https://github.com/stormhop/kurlo/releases/latest) and compare its SHA-256 checksum. ## Windows SmartScreen warns about the installer The NSIS installer is not currently Authenticode-signed, so SmartScreen may flag it. Confirm that it came from the official releases page, verify its checksum, then use **More info → Run anyway** only if you trust the download. ## Auto-updates aren't working - Check manually from **Settings → About**. - If you want background installation, enable **Settings → About → Install updates automatically**. - Make sure `https://github.com/stormhop/kurlo/releases/latest/download/latest.json` is reachable — corporate proxies sometimes block GitHub release downloads. - If you're on an unreleased dev build, auto-update is disabled by design. ## Postman compatibility — what doesn't carry over? See [Import & export](https://kurlo.dev/docs/guides/import-export/). Short version: common `pm.*` scripts import into Kurlo's sandboxed script fields — including `pm.sendRequest`, `pm.collectionVariables`, and `CryptoJS` request signing. What still needs a rewrite: scripts that `require` a Node.js module or external package, anything using `async`/`await` or `setTimeout`, Visualizers, and cloud-only Postman features. Monitors have no direct equivalent — use the [CLI runner](https://kurlo.dev/docs/guides/cli-runner/) on a schedule. Mock servers do have one, and it is local: Kurlo serves a collection's [saved examples](https://kurlo.dev/docs/guides/examples/) over HTTP on your own machine. See [Mock server](https://kurlo.dev/docs/guides/mock-server/). ## How do I report a bug? [Open an issue](https://github.com/stormhop/kurlo/issues) with: - Version (Settings → About). - Platform and OS version. - Steps to reproduce. - Anonymized request if relevant (strip auth + sensitive bodies). # Support Kurlo Source: https://kurlo.dev/docs/support/ > Kurlo is free for teams of any size. Here is how to help it keep going. Kurlo has no paid plan and will not get one. Every feature is in the free, [MIT-licensed](https://github.com/stormhop/kurlo/blob/main/LICENSE) app, with no account and no seat limit. ## Support development on Boosty If Kurlo saves you time, you can support it on [Boosty](https://boosty.to/kurlo) with a monthly subscription or a one-time tip. The money pays for the server, macOS code signing and the time that goes into new features. Supporters get: - posts on what is being built and what comes next; - release candidates before each public release; - a vote on upcoming features. ## Other ways to help - [Star Kurlo on GitHub](https://github.com/stormhop/kurlo). A star helps other people find it. - [Report a bug or ask a question](https://github.com/stormhop/kurlo/issues). In the app, **Settings → Support → Copy diagnostics** collects the details that help fix it. - [Contribute](https://github.com/stormhop/kurlo/blob/main/CONTRIBUTING.md) code or docs. The Boosty link is also in the app under **Settings → Support**. # Privacy & security Source: https://kurlo.dev/privacy/ > Kurlo is local-first. What stays on your machine, what leaves it, and how your data is protected. Kurlo is a local-first desktop application. There is no Kurlo backend, account system, cloud sync, usage analytics, crash reporting, or telemetry. Network access occurs only for product features that require it, such as requests, Git operations, OAuth flows, schema introspection, and update checks. This page explains what the Kurlo app stores, when it connects to the network, and how kurlo.dev measures visits. None of it has to be taken on trust: Kurlo is open source under the MIT license, so every claim below can be checked against the code at [stormhop/kurlo](https://github.com/stormhop/kurlo), and the binaries can be reproduced from that source. ## What Kurlo stores on your machine Workspace state, requests, environments, request history, cookies, secrets, and preferences are written to local disk. Request history records what was sent and what came back, including the response body, which is stored in its own file under `history/` and encrypted with the same key as the rest of the local profile. A response over 2 MB keeps only its head, and a binary response keeps no body at all. Kurlo is a single-tenant, file-based application: | Platform | Location | |----------|----------| | macOS | `~/Library/Application Support/Kurlo/` | | Windows | `%AppData%\Kurlo\` | | Linux | `~/.config/Kurlo/` or `$XDG_CONFIG_HOME/Kurlo/` | Inside that directory you may find: - `requests.json` — an AES-256-GCM encrypted JSON envelope containing local profile state, history, workspace cookies, Git-local secret values, and storage metadata. - `request-store.key` — a base64-encoded recovery copy of the encryption key, written with owner-only `0600` permissions. - `request-store.key.dpapi` — an additional Windows DPAPI-protected key copy. - `preferences.json` — the configured default workspace location, cookie sync settings, and [AI connections](https://kurlo.dev/docs/guides/settings/ai/#ai) with their keys encrypted by the request-store key. Other UI preferences are stored by the desktop WebView. - `agent-chats/` — [agent](https://kurlo.dev/docs/guides/agent/) chats and copies of sent attachments, encrypted on disk. Kurlo keeps up to 200 unarchived chats across the local profile for up to 90 days of inactivity. Archived chats and their attachments are kept until you delete them. Markdown exports are unencrypted files saved at a location you choose. - `agent-activity/` — the encrypted log of tool calls made by the agent and by assistants connected through `kurlo mcp`, with the files they changed, kept for 30 days. - `workspaces/` — the default folder-backed YAML workspace location. If you select another workspace folder or Git repository, its shared YAML files live at that selected path. Those files are intentionally human-readable and are not encrypted as a unit. You can move, back up, or delete this directory at any time. Deleting it returns Kurlo to a clean state on next launch. ## Encryption at rest The request store is encrypted with **AES-256-GCM**: - A fresh 256-bit key is generated locally the first time Kurlo starts. - The key is additionally stored in the OS credential store wherever possible: - **macOS** — Keychain (the same store used by Safari / login items) - **Windows** — DPAPI (current user; non-exportable to another user account) - **Linux** — libsecret via `secret-tool` (GNOME Keyring, KWallet, etc.) - Kurlo also keeps `request-store.key` as a recovery copy even when the credential-store write succeeds. This avoids losing encrypted data if the credential-store entry disappears. - The recovery file is owner-readable only, but it is not protected by another secret. Anyone who can read both `requests.json` and `request-store.key` can decrypt the local profile. - Every encrypted payload uses a unique random nonce. There is no nonce reuse across writes. For folder/Git workspaces, Kurlo replaces sensitive YAML values with `{{kurloSecret:...}}` placeholders and stores the real values inside the encrypted local profile. ## What leaves your machine A few bounded categories of network calls happen on your behalf: 1. **Requests you send.** This is the whole point — when you press Send, Kurlo opens a connection to the host you typed in the URL bar. The request is built on your machine and sent directly unless you configured a system, global, or per-request proxy. 2. **Auto-update checks.** On launch (and when you press *Check for updates*), Kurlo fetches `latest.json` from the public release repository (`github.com/stormhop/kurlo`) over HTTPS. Release builds verify the downloaded binary by SHA-256 and minisign signature. No usage data is included in the request. 3. **OAuth 2.0 authorization and token calls.** Kurlo can open the provider's authorization page and call the authorization/token endpoints you configured. 4. **GraphQL schema introspection.** When you load a GraphQL schema URL in the Schema tab, Kurlo sends a standard introspection query to that URL. 5. **Git remotes.** Clone, fetch, pull, push, remote tests, and remote branch actions contact the Git server you configured. 6. **An OpenAPI spec you import from a URL.** *Import collection -> OpenAPI / Swagger from URL* fetches the link you paste, through the same sender your requests use, so it honours your proxy settings and the response cap. Cookies are not attached to it. 7. **AI connections.** When you test an AI connection or load its models, Kurlo calls that provider's model list (and, for OpenRouter, its key check) with your key. Connecting OpenRouter opens openrouter.ai in your browser; after you approve, OpenRouter sends the browser to `kurlo.dev/connect/openrouter/`, a static page that forwards it to Kurlo on `127.0.0.1`, and Kurlo exchanges the code for a key at `openrouter.ai/api/v1/auth/keys`. The code passes through that page's URL but cannot be exchanged without a secret that never leaves Kurlo, and it expires after ten minutes. If kurlo.dev cannot be reached, OpenRouter returns to `localhost` directly. *Find local models* only contacts `127.0.0.1` ports 11434 and 1234. These calls follow the system proxy environment variables, not the proxy configured in Kurlo. Proxy settings can route these requests through your selected system or custom proxy. There is no separate telemetry channel or first-launch ping. ## Ports Kurlo opens on your machine Four features bind a local listener. All four are loopback-only (`127.0.0.1`, and `::1` for the OpenRouter sign-in), so nothing on your network can reach them, and none of them is open unless you start it. | Listener | When it exists | What it serves | |----------|----------------|----------------| | OAuth 2.0 redirect | Only while an Authorization Code sign-in is in flight, on an ephemeral port | The single `/callback` that receives the authorization code, then closes | | OpenRouter sign-in | Only while *Connect OpenRouter* is waiting (at most five minutes), on an ephemeral port | The single `/callback` that receives OpenRouter's code, then closes | | [Cookie sync](https://kurlo.dev/docs/guides/cookies/sync/#sync-cookies-from-your-browser) bridge | While cookie sync is on (ports 3199-3203) | Pairing and the WebSocket a paired browser pushes cookies over. Extension origins only; a web page probing the port gets a `403` | | [Mock server](https://kurlo.dev/docs/guides/mock-server/) | While you have it running, on the port you choose | The saved examples of the collection you pointed it at — status, headers and body as recorded. Any program on your machine that can reach the port can read them, so treat a mock made from real responses accordingly. In a browser, only a page served from this machine is answered; a site on another host gets a `403` | ## Scripting safety Pre-request and test scripts run in a sandboxed JavaScript VM by default, with a legacy [Tengo](https://github.com/d5/tengo) engine for existing requests: - Imports, `require`, process access, filesystem access, and direct network sockets are disabled. - Execution is capped at **2 seconds** per script. - Scripts have access only to the explicit `pm.*` API (request/response/variables/environment/log). They cannot reach the file system, spawn processes, or open network sockets directly. Any HTTP call goes through the regular request engine. ## Cookies By default Kurlo maintains a cookie jar across requests, just like a browser. Cookies are stored in encrypted `requests.json`. You can: - Inspect and edit cookies per domain in the Cookies modal (the icon next to the URL bar). - Clear all cookies from that modal. - Disable the cookie jar for an individual request in *Per-request settings*. Cookies are never transmitted anywhere except in the request to the domain that set them, following standard browser rules. **Cookie sync** (Cookies window -> *Sync*) is off unless you turn it on. When on, Kurlo opens a listener bound to `127.0.0.1` that a browser extension can find and ask to connect to; you approve the request in Kurlo by matching a six-digit code, and only then does Kurlo hand over a token. The extension then holds a WebSocket to that port and pushes cookies for the domains you allowlist there, and only those. The token and the allowlist are stored in `preferences.json`. Cookies travel browser -> Kurlo over loopback only, and a snapshot replaces what the jar held for those domains. *Disconnect* mints a new token and drops the browser immediately. ## Data export and deletion - **Export** - *Settings -> General -> Data -> Export all data* writes workspace data, history, cookies, secrets, and selected preferences to a plaintext JSON file you choose. External Git repositories, the global proxy password, and some local UI preferences are not bundled. See [Backup & recovery](https://kurlo.dev/docs/guides/backup-recovery/). - **Import** — replaces the current profile with a previous export. This is destructive; Kurlo shows a confirmation dialog before running. - **Delete** — quit Kurlo and remove the directory listed under [What Kurlo stores on your machine](#what-kurlo-stores-on-your-machine). ## Documentation feedback When you rate a documentation page, kurlo.dev sends the page path, your vote, and any reason you select to its GoatCounter instance. The feedback form has no free-text field and sends no account details. ## Reporting a security issue If you find a vulnerability, please follow the process in our [security policy](https://github.com/stormhop/kurlo/blob/main/SECURITY.md). Please do not file public GitHub issues for security problems. ## Local coding agents Connecting Codex starts the installed CLI on this computer. The CLI owns authentication and sends conversation content and tool results to its configured provider. ChatGPT sign-in uses the official Codex flow; Kurlo does not collect subscription access or refresh tokens. Kurlo saves the executable path and default model in its preferences and associates each local chat with a native Codex session ID. Kurlo's chat copy is encrypted in its profile. Codex separately stores native sessions and credentials according to its own settings. Deleting a Kurlo chat or removing the connection does not delete the native Codex copy or sign you out. Workspace changes still pass through Kurlo's approval controls. Claude Code runs through the installed CLI. Its configured provider receives prompts and tool results. Kurlo associates its encrypted chat with the native Claude Code session ID. The CLI manages its credentials and native transcript separately from Kurlo. # Changelog Source: https://kurlo.dev/changelog/ > Notable Kurlo changes and links to the exact notes for each published release. This page summarizes the notable-change log maintained in the source repository. For the exact notes and artifacts attached to every published tag, use the [Kurlo releases page](https://github.com/stormhop/kurlo/releases). ## Unreleased ### Added - **Request authentication in JavaScript.** Pre-request and test scripts can read the active auth type and parameters through `pm.request.auth`, including inherited auth. - **Postman v3 collection export** writes a YAML folder for Postman Desktop with native gRPC, GraphQL, and HTTP requests. Postman v2.1 JSON remains available. See [Export to Postman v3](https://kurlo.dev/docs/guides/import-export/postman/#export-to-postman-v3). ### Fixed - **k6 request handling.** Load tests now honor request variables and redirect settings, preserve encoded path segments, keep query parameters on URLs with fragments, and send repeated form fields. - **k6 data and validation.** Runs preserve large numeric IDs and variable defaults when a data row omits a field. Unreadable or invalid data, unsupported JSON paths, and incompatible extraction patterns produce errors before the run. - **Load test edits and results.** Switching tests flushes pending autosave edits. Edits made during a save survive, failed saves can be retried, and running tests lock their editor. Collections with matching test IDs keep separate results, summaries, and reports. - **Script saving.** In manual-save mode, Ctrl+S (Cmd+S on macOS) saves edits to the active collection or folder, including its scripts. - **HTTP body fonts.** Request and response bodies use the same monospace font and size. - **OpenAPI imports** stop if the intended workspace is no longer active when the spec arrives. - **OpenAPI and Postman imports** report save failures and let you retry saving imported requests. - **Secret variables** keep their IDs when loading and autosaving a Git workspace. ## 3.1.4 ### Added - **Postman v3 collections**: import the Git folder of `.request.yaml` files Postman v12 writes, or drop it into the window; collections, requests, auth, scripts, examples, environments and globals come across. See [Import and export](https://kurlo.dev/docs/guides/import-export/postman/#postman-v3-folders). - **Move requests between folders** by dragging them onto a folder or back onto the collection header. See [Workspaces](https://kurlo.dev/docs/guides/workspaces/). - **PFX/P12 client certificates** for mTLS over HTTP and gRPC, with a password and certificate chain. See [Request settings](https://kurlo.dev/docs/guides/request-settings/). - **Performance dock**: CPU, memory and Kurlo's processes from the status bar gauge or Cmd/Ctrl Alt P. See [Performance dock](https://kurlo.dev/docs/reference/performance/). ### Fixed - **cURL paste keeps what the command sends**: uploads, Bearer, Digest, NTLM and AWS auth, `--url-query` and combined flags like `-sSLo out.json` come across; options Kurlo cannot import stop the paste with a message. - **YAML imports read multi-line `[...]` and `{...}`**, and several `---` documents in one file are rejected instead of merged. - **No false unsaved changes** after renaming a collection in manual-save mode. - **Safer Git actions**: no stale autosave after a checkout or pull, and Git waits while an agent writes the workspace. - **Responses and chats stay on their request**, and restored AI requests keep their chat. - **Requests and connections always end**: unconfirmed cancels, unanswered WebSocket closes and deleted workspaces. - **Lower memory use** for long gRPC streams, interrupted downloads and large signed file bodies. - **Fewer places secrets show** in MCP `get_request` and `kurlo run` output. - **Scripts behave the same everywhere**: runaway regexes time out, MCP logs appear once, `$isoTimestamp` has milliseconds in the CLI. - **Faster with large workspaces**: big Git diffs, the JSON filter, the sidebar filter and typing in long requests. - **Steady scrolling in long lists**, script editors that fill the panel, and update notes cut on a complete line. ## 3.1.3 ### Added - **Client certificates for gRPC**: the gRPC **Settings** tab has **Client certificate (mTLS)**, like HTTP, used for the call and for reflection whenever TLS is on. See [Request types](https://kurlo.dev/docs/guides/request-types/grpc/). - **Script output you cannot miss**: a failing script puts a red banner above the response body and a count on the **Scripts** tab, the output stays visible under "Could not send request", `console.warn` / `console.error` are coloured, every `pm.sendRequest` call is logged, and long or dropped log lines are marked. See [Logging](https://kurlo.dev/docs/reference/scripting-api/logging/#logging). - **`{{variables}}` in every auth field**: auth fields suggest variables after `{{` and flag undefined ones; a secret field holding only `{{token}}` shows it as text. See [Authentication](https://kurlo.dev/docs/guides/authentication/bearer/). - **Preview tabs**: enable **Settings → General → Preview tabs** to reuse one temporary request tab while browsing. Double-clicking, editing or running the request keeps its tab open. Off by default; the preference and preview survive a restart. See [App settings](https://kurlo.dev/docs/guides/settings/start-and-tabs/#preview-tabs). ### Changed - **Less JavaScript on the first load**: the code editor is not loaded at start-up, which removes about 350 KB of JavaScript before the window is ready. Kurlo warms it in the background right after the first paint, so the first visit to the Body or Scripts tab does not wait. ### Fixed - **`pm.sendRequest` works like Postman**: string headers, disabled headers, `urlencoded`, `formdata` and `graphql` bodies and `Content-Type` from the body are handled, so servers no longer answer 415, and the script timeout cancels a running call. See [`pm.sendRequest`](https://kurlo.dev/docs/reference/scripting-api/send-request/). - **Scripts behave as written**: pre-request `pm.test` results show and count everywhere, GraphQL body updates, form edits and `pm.globals.unset` keep what they should, and secret values in test names are masked. - **gRPC requests inherit collection auth**: **Inherit auth** now uses the collection's or nearest folder's credentials and is offered in the gRPC Auth tab. - **Saves no longer lose or undo edits**: collection settings are written when you leave early, Reset defaults clears JavaScript scripts too, and an older queued save cannot overwrite a newer one. - **Environment pages behave**: editing on page 2 or later stays on that page, and the page count is right. - **Idle windows stop burning CPU**: the perched bird and the status indicators settle after a few moves instead of redrawing the window every frame. - **Imported names keep their slashes**: `Billing / Invoices` stays one request instead of becoming a folder. - **`kurlo run` fixes**: flags around the workspace folder, environments scoped to their workspace, `--export-globals` with script values, UTF-8 BOM in data files, `--verbose` script output and masked secrets in reports. See [CLI runner](https://kurlo.dev/docs/guides/cli-runner/). - **`kurlo mcp` fixes**: combined curl flags import, echoed secret headers are masked, and `kurlo mcp install` rejects an unknown `--env`. See [MCP server](https://kurlo.dev/docs/guides/mcp-server/). ## 3.1.2 ### Fixed - **No Documents permission prompt on macOS**: 3.1.1 watched every folder above the workspace, so macOS asked again for access to Documents at start-up. Kurlo now watches only the workspace folder. ## 3.1.1 ### Added - **Drop files to import**: drop a `.http`, `.rest`, Postman, Insomnia, OpenAPI or HAR file anywhere in the window to import it, instead of the window showing the file's text. - **JetBrains HTTP Client scripts run**: the sandbox understands `client`, `request` and `response`, so scripts imported from `.http` files work as written. See [JetBrains HTTP Client globals](https://kurlo.dev/docs/reference/scripting-api/compatibility/#jetbrains-http-client-globals). ### Changed - **One loader everywhere**: every wait in the app — responses, gRPC and MCP calls, diffs, history, cookies, examples, the mock server, model lists, settings checks and the Cancel button — shows the flying Kurlo bird instead of spinners and *Loading…* captions. - **Claude Code models stay current**: models, the default and effort levels come from your installed CLI. Kurlo keeps the last successful list for temporary failures and preserves the model in existing chats. - **Saving an edit writes only what changed**: from the first edit after opening, Kurlo sends and rewrites just the edited requests, so an autosave in a workspace with 1,300 requests takes about 20 ms instead of 280 ms. Structural changes and files edited outside Kurlo still use the full save. - **Large workspaces open and save faster**: examples are read in the background after a workspace opens, so a 1,300-request workspace opens in about 190 ms instead of 430 ms; the full save takes about 170 ms instead of 290 ms, and typing no longer rebuilds the sidebar. - **Git status after a save checks only the saved files**, without refreshing the branch list on every edit. - **File changes are noticed through the system**: FSEvents, `ReadDirectoryChangesW` and inotify replace the scan every second, which remains only as a fallback. ### Fixed - **Edits save on the first launch**: on a new installation Kurlo refused every save with *changes could not be saved*, so nothing reached the disk. An empty profile now counts as a fresh start. - **`.http` import keeps scripts out of requests**: pre-request scripts no longer make a request disappear, response handlers no longer land in the body, and XML bodies starting with `<` are kept. - **Import dialog shows `.http` and `.rest` files on Linux**: import opens the system dialog filtered to the chosen format. - **Tengo script timeouts**: Tengo scripts respect the configured script timeout instead of always using two seconds. - **Compact release notes in About**: long update notes show about ten lines and a link to the full changelog on the website. - **Mock server with thousands of examples**: the route list reads only methods, paths and statuses and the server reads responses from disk, so it opens quickly, scrolls without blank gaps and keeps the sidebar animation smooth; hiding the sidebar no longer moves the list away from the route you were looking at. - **The sidebar hides and shows at once**: toggling it no longer restyles the whole window, so the slide starts without a pause in large workspaces. - **Large workspaces stay responsive**: saving no longer re-encodes or resends examples already on disk, so typing, saving and switching requests do not stall with hundreds of requests. - **Long lists scroll the same way everywhere**: the collection runner has no page buttons any more, and agent activity loads older calls as you scroll; its search and summary cover the whole log. - **Chats and Git history load more as you scroll**: a long agent chat loads earlier messages as you scroll up instead of through a button, and Git history loads 100 older commits at a time. - **Links without underlines**: links change colour on hover instead of being underlined. - **Saving a response as an example stays on its request**, even if you open another request while examples are loading. - **Editing a request with large examples stays light**: unchanged examples are no longer resent on every save. - **Less memory after deleting requests**: previous responses of deleted requests are freed. - **Git paths with spaces**: such files show without quotes in the Git panel and their diffs open. - **No macOS suggestions in text fields**: filters and search boxes no longer show autocorrect or autocomplete pop-ups. - **Settings open at once**: settings and search are prepared in the background after start-up. - **Straight selection edge in editors**: a multi-line selection starts at the text column on every line instead of stepping out into the indent. ## 3.1.0 ### Added - **OpenAPI sync**: keep a collection linked to its spec URL or file, with no sync limit. Kurlo checks it in the background, shows new, changed, conflicting and removed endpoints for review, and merges three ways so your edits, scripts and tests stay. See [OpenAPI sync](https://kurlo.dev/docs/guides/openapi-sync/). - **`kurlo openapi check`**: flag spec drift in CI with exit code `1`, or ask an agent through the `check_openapi_sync` MCP tool. See [Contract drift](https://kurlo.dev/docs/guides/cli-runner/openapi/#contract-drift-with-kurlo-openapi-check). - **Request variables**: a **Vars** tab on every request with Pre Request variables that override the environment and Post Response variables taken from the response with expressions such as `res.body.token`. Imported from Bruno and Insomnia folders. See [Request variables](https://kurlo.dev/docs/guides/environments/request-variables/). - **JWT Bearer auth**: Kurlo signs a fresh JWT on every send from a secret or a private key, with claims, an optional lifetime and a token preview. See [JWT Bearer](https://kurlo.dev/docs/guides/authentication/jwt/). - **Assertions**: check the status, time, size, a header or a JSON field of a response without code, in **Scripts → Assertions**. Results show with the tests and count in the runner, `kurlo run` and `kurlo mcp`. See [Assertions](https://kurlo.dev/docs/guides/scripting/assertions/). - **Undo deletes**: a deleted request, folder, collection or environment can be brought back with **Undo** or from * *Recently deleted** until you quit Kurlo. See [Restoring deleted items](https://kurlo.dev/docs/guides/workspaces/starred/#restoring-deleted-items). - **Environment colors**: mark an environment red, amber, green, blue or gray, and the title bar switcher, environment lists and pickers show it. See [Coloring an environment](https://kurlo.dev/docs/guides/environments/secrets/#coloring-an-environment). - **Reorder requests by dragging** above or below another request in the same collection or folder. See [Reordering requests](https://kurlo.dev/docs/guides/workspaces/requests/#reordering-requests). - **Autosave delay**: choose how long Kurlo waits after an edit before saving. See [Saving](https://kurlo.dev/docs/guides/settings/saving/). - **Skip TLS check on URL import** for specs served with a self-signed or internal certificate. See [From a URL](https://kurlo.dev/docs/guides/import-export/openapi/#from-a-url). - **Show in Finder / Explorer**: open the YAML file of a request or the folder of a collection from its menu. See [The request ⋯ menu](https://kurlo.dev/docs/guides/workspaces/requests/#the-request--menu). - **Edit menu in text fields**: right-click a field or a code editor for Cut, Copy, Paste and Select all. See [Keyboard shortcuts](https://kurlo.dev/docs/reference/keyboard-shortcuts/). - **Kurlo docs in search**: the search palette offers the documentation first, and with a query it searches the docs in your browser. See [Command palette](https://kurlo.dev/docs/guides/workspaces/command-palette/). ### Performance Large workspaces, such as an OpenAPI import of 500 requests with 3,400 examples, are faster at every step: - **Opening**: the workspace is read once, while the window is still loading, and examples load only when needed. The sidebar is filled about 0.5 s after launch. - **Saving**: a save sends about a tenth of the data and opens about a fifth as many files. - **Quitting and closing tabs**: nothing is written when nothing changed, and a closed tab disappears at once. Quitting a 1,300-request workspace takes about 0.3 s on macOS instead of 1–7 s. - **Scrolling**: the sidebar and the Git panel no longer show blank patches on a fast fling, draw the visible rows first, and keep native trackpad momentum. Git history loads older commits as you scroll. - **Idle**: a minimised window stops checking the workspace folder until you come back. ### Changed - **Portable app for Windows**: the standalone `.exe` is now named `kurlo--windows--portable.exe` and is on the download page. See [Installation](https://kurlo.dev/docs/getting-started/installation/windows/). - **OpenAPI servers import like Bruno**: requests use `{{baseUrl}}`; document servers become a collection variable, path and operation servers go into the request's **Vars** tab, and alternatives such as Sandbox are switched-off rows you can tick instead. See [From OpenAPI / Swagger](https://kurlo.dev/docs/guides/import-export/openapi/#from-openapi--swagger). - **Imported collections start collapsed**, and remember your later expand and collapse choices. - **New requests start as drafts with manual saving**: **Add request** opens a draft that already uses the collection's and folder's settings, and **Save** puts it there. Untouched drafts close without asking. See [Creating a request](https://kurlo.dev/docs/guides/workspaces/requests/#creating-a-request). - **Starred requests are personal**: stars stay on your machine instead of in request files and Git, and the group scrolls within ten rows. See [Starred (favourites)](https://kurlo.dev/docs/guides/workspaces/starred/#starred-favourites). - **Search moved to the status bar**: open it from **Search** at the bottom right or with `Cmd/Ctrl K`. See [Command palette](https://kurlo.dev/docs/guides/workspaces/command-palette/). - **More room in the tab row**: close buttons appear on hover or keyboard focus without moving the tabs, and on Windows and Linux there is always a free spot to drag the window by. See [Window title bar](https://kurlo.dev/docs/guides/settings/appearance/). - **Code snippet is next to Send** in the URL row. - **Panels fold in and out**: the sidebar, Agent mode's **Chat details** and **Code snippet** open and close smoothly; reduced motion disables the animation. - **Sidebar context menus open right under their row**, and above it near the bottom of the window. ### Fixed - **Protection against wiping a workspace**: Kurlo will not save over a workspace it could not read, or save a state that drops every workspace in the folder. - **Locked workspaces explain themselves**: a missing workspace or collection file locks only its own workspace, and the overview shows which file needs fixing. - **Imported requests that would not load**: a request whose description began with a line break, for example from an OpenAPI import, loads again after a restart. - **OpenAPI import reads generator-written YAML** from Jackson, springdoc and similar tools. See [OpenAPI / Swagger](https://kurlo.dev/docs/guides/import-export/openapi/#from-openapi--swagger). - **No false unsaved dot** when opening a request with path variables. - **Send errors** such as a TLS certificate error show at once. - **Long URLs stay on one line**: the URL bar scrolls the text sideways instead of growing downwards. See [Your first request](https://kurlo.dev/docs/getting-started/first-request/). - **Concurrent saves** no longer mistake a file being replaced for a missing one. - Sidebar rows no longer keep their hover look after dragging, the load test environment selector keeps a fixed width, * *Open log folder** works on Windows again, **All open tabs** shows its list again, and the macOS workspace switcher icons no longer shift by a pixel. ## 3.0.4 ### Added - **Filter JSON responses** with JSONPath or a jq-style path. See [Filtering a JSON response](https://kurlo.dev/docs/guides/response-viewer/search-and-filter/#filtering-a-json-response). - **Saved WebSocket and Socket.IO messages**, kept with the request: up to 100 per request, with search. See [Saved messages](https://kurlo.dev/docs/guides/request-types/websocket/#saved-messages). - **Import a .env file** into an environment. See [Importing a .env file](https://kurlo.dev/docs/guides/environments/manage/#importing-a-env-file). - **Fable 5.2** in the Claude Code model menu. See [Agent](https://kurlo.dev/docs/guides/agent/). - Ten new themes: GitHub Light, GitHub Dark Dimmed, JetBrains Light, JetBrains Dark, One Dark, Tokyo Night, Everforest, Flexoki Paper, High Contrast Light and High Contrast Dark. ### Removed - Light Monochrome, Light Pastel, Dark Monochrome, Dark Pastel, Catppuccin Frappé and Catppuccin Macchiato. A saved choice moves to Light, Flexoki Paper, Dark, Everforest or Catppuccin Mocha. ### Changed - **Supported macOS is now 15 Sequoia or later.** Kurlo still starts on macOS 12–14, but those versions are no longer tested. Windows and Linux are unchanged. - Environments open one at a time; the **Matrix** is one click away, lets you pick its columns and stays smooth with hundreds of variables. See [Comparing environments](https://kurlo.dev/docs/guides/environments/manage/#comparing-environments). - Cookies open as a sidebar section with a page per domain and Kurlo's own date and time picker for **Expires**. - Workspace **Notes** became a **README**, kept as `README.md` in the workspace folder. - Clearer workspace and collection overviews with rename in place and a **•••** menu. - Environments, global variables, collection and folder settings and the README use the same **Revert** and **Save** buttons as a request. See [Settings](https://kurlo.dev/docs/guides/settings/). - Theme contrast and highlight colours are more consistent, and dialogs dim the window without blurring it. - On macOS, the title area is one band across the whole window. - Markdown previews over 256 KB show a note instead of freezing the screen. ### Fixed - **Manual save covers environments, global variables and the workspace README.** See [Saving](https://kurlo.dev/docs/guides/settings/saving/). - **The Collection Runner no longer sends unchecked requests** when opened from the activity rail. - **Network errors mask environment secrets** before they reach history or script results. - In the **Matrix**, **×** no longer deletes a variable set in only one environment, and typing into a **Not set** cell keeps every character. - A long name no longer pushes the top bar and editor off screen. - A Claude Code CLI that signed out shows **Signed out** and a **Sign in** button in Settings → AI. - A Socket.IO event sent with an empty message carries no arguments. - Long names in the GraphQL field list and on the AI connection button are cut with an ellipsis. - Background MCP, gRPC, HTTP and SSE results stay with their own request tab. - Redirect limits, timeouts, proxy DNS errors, `pm.response.body` and NTLM traces behave correctly. - Saving examples and failed metadata reads no longer change unrelated workspace files. - The cookie editor, agent chat scrolling, Git diff file headers and list scrolling over row labels work as expected. ## 3.0.3 ### Changed - **Pinning environments.** The collection Overview shows only pinned environments and adds others from a search picker instead of a checkbox for every environment. See [Pinning environments to a collection](https://kurlo.dev/docs/guides/environments/pin/#pinning-environments-to-a-collection). - **Environment switcher.** Scrolls with many environments and adds a search field above eight; environment dropdowns get search too. See [Switching environments](https://kurlo.dev/docs/guides/environments/manage/#switching-environments). - **Steady scrolling.** Dropdown lists and panels no longer bounce past their edges. ### Fixed - **Unsaved mark on new requests.** Undoing an edit in a request created from a collection's settings no longer leaves it marked as changed. ## 3.0.2 ### Fixed - **Exports without secrets.** Remove custom API keys, client-key passwords, proxy credentials and secrets in saved example requests; detect secrets in settings and examples before exporting. - **Agent host approvals.** Check the actual destination after applying request and session variable overrides. - **CLI and MCP collection variables.** Keep each collection's variables separate when running requests. - **Environment changes during sends and runs.** Collection runs keep their original environment, and gRPC script updates stay with the environment that started the request. - **gRPC scripts.** Honor `pm.execution.skipRequest()` and pass pre-request collection-variable changes to test scripts. - **Compressed SSE responses.** Read events when an explicit `Accept-Encoding` header requests compression. - **Duplicate request.** Keep pending edits in the source request when duplicating before autosave finishes. - **k6 export.** Resolve templates in header names, API-key header names and URL-encoded field names without generating invalid JavaScript. - **Long environment lists.** Keep rows at full height and let the sidebar list scroll, also after resizing the window or switching tabs. - **Selecting a response.** Cmd/Ctrl+A in the response panel selects only the body, and a selection dragged from the body leaves warnings above it out. - **Creating environments through the agent.** Create many environments with their variables in one batch; `values` or `variables` can be a list of rows or a `key: value` object. See [Batch edits](https://kurlo.dev/docs/guides/mcp-server/edit/#batch-edits). ## 3.0.1 ### Added - **Environments pinned to a collection.** Pin a collection's environments so the switcher shows only them while you work in it, select its default environment when you open it, and go back to your previous environment when you leave it. See [Pinning environments to a collection](https://kurlo.dev/docs/guides/environments/pin/#pinning-environments-to-a-collection). ## 3.0.0 ### Added - **Agent mode.** Ask the Kurlo agent on your own model, Claude Code or Codex in plain words to run requests, explain failures, write tests and import specs. It asks before every change, can follow an approved plan, work on its own Git branch and use your MCP servers, and keeps chats on this computer. See [Agent](https://kurlo.dev/docs/guides/agent/). - **Kurlo tools in AI requests.** Give an AI request's model Kurlo's read and run tools for the workspace, and pick which AI connection a **Kurlo connection** request uses. See [Kurlo tools](https://kurlo.dev/docs/guides/request-types/ai/#kurlo-tools). - **Create PR from the Git screen.** Open a pull or merge request page for a pushed branch. See [Daily Git flow](https://kurlo.dev/docs/guides/git-workspaces/workflow/). - **AI connections.** Settings → AI connects OpenRouter by signing in, an Anthropic, OpenAI or compatible key, or a local Ollama or LM Studio model. Keys are encrypted and stay out of workspace files, and AI requests can use the default connection. See [AI](https://kurlo.dev/docs/guides/settings/ai/#ai). - **Environment inheritance.** An environment takes the variables it does not set from a parent environment; the matrix shows where each value comes from. See [Inheriting from another environment](https://kurlo.dev/docs/guides/environments/manage/#inheriting-from-another-environment). - **Folder defaults.** Folders set headers, auth, scripts and tests for the requests inside them, and Postman and Bruno folder auth and scripts import onto the folder. See [Folder defaults](https://kurlo.dev/docs/guides/collection-defaults/folders/). - **NTLM sign-in.** HTTP requests can use NTLMv2 auth. See [Authentication](https://kurlo.dev/docs/guides/authentication/). - **Suggestions while you type.** The URL field completes URLs from history and saved requests, and finds a request by name; a JSON body offers the next key from the request's examples. `Tab` accepts. See [Suggestions while you type](https://kurlo.dev/docs/guides/request-types/http/#suggestions-while-you-type). - **Rename environments from their names.** Edit the environment name directly in the editor, or double-click it in the sidebar. **Rename** focuses the name field; Enter or leaving the field saves, and Escape cancels. - **Zoom in Settings.** **Settings → Appearance** has a **Zoom** row with −, + and **Reset**. See [Appearance](https://kurlo.dev/docs/guides/settings/appearance/). ### Changed - **Settings layout.** Every Settings page now shares one layout: a title, then grouped rows with the control on the right. General shows all settings at once, Proxy shows its server fields only when on, and the AI page shows Codex with its model and plan limits first. See [App settings](https://kurlo.dev/docs/guides/settings/). - **Cookie jar redesign.** Domains on the left, cookies in a table with expiry and flags, and an editor with **Fields** and **Raw** modes. The **Sync** tab uses Settings-style cards. See [Managing cookies](https://kurlo.dev/docs/guides/cookies/manage/#managing-cookies). - **Linux window without the system title bar.** Kurlo draws its own title bar on Linux, like on Windows, and drops the GTK menu bar. `Ctrl Q` quits and zoom is in **Settings → Appearance**. ### Fixed - **No scroll bars on a short AI prompt.** The **Prompt** field of an AI request fits a short request panel and scrolls only when its text does not fit. See [AI](https://kurlo.dev/docs/guides/request-types/ai/#ai). - **A clear message when an AI request's saved key is missing.** Kurlo says the key from the Auth tab is not on this computer instead of showing an internal reference. See [AI](https://kurlo.dev/docs/guides/request-types/ai/#ai). - **Open Settings → AI goes to the connections and models.** The model box and the request bar of an AI request open Settings → AI on **Kurlo agent**. See [AI](https://kurlo.dev/docs/guides/request-types/ai/#ai). - **Close tab closes the Mock tab.** `Cmd+W` closes the Mock server tab like the other tabs. See [Mock server](https://kurlo.dev/docs/guides/mock-server/start/#starting-it). - **URL-encoded bodies keep the order of their fields.** Fields are sent in the order of the form instead of sorted by name. - **Sending a request.** Fixed a rare crash to the error screen right after the first request was sent. - **Inherited secrets.** Script changes in a child environment keep inherited variables secret, masked and outside workspace YAML. - **OAuth and tab switching.** Tokens stay with the original request, Send keeps its original request and variables, and the runner uses refreshed tokens for HTTP and gRPC. - **Digest redirects.** Authentication follows the forwarding setting and is blocked on HTTPS-to-HTTP redirects. - **Workspace cookies.** Pending cookie updates cannot overwrite another workspace's jar after switching. - **Cookies without their secret.** A workspace cookie whose secret value is missing on this computer is no longer sent as `{{kurloSecret:…}}` text; the Cookies window marks it *no value*. - **Saved runner results.** Totals and verdicts cover the full run; the 500 retained details prioritize failures, and limited details are labelled in the runner and HTML report. - **Mock server headers and `HEAD`.** Repeated headers such as several `Set-Cookie` lines are all replayed, and `HEAD` is answered from the `GET` example. - **Variables in MCP tools and runner gRPC.** An AI request's MCP tools resolve their own collection variables and globals, and gRPC requests in the runner see globals set earlier in the run. - **cURL `--data-raw '@…'`.** The body is imported as text instead of a file. - **AI requests in Git workspaces.** Workspace YAML accepts provider strings, so requests using the default Kurlo connection or a custom provider can load. - **Owner-only variable exports.** `kurlo run --export-environment` and `--export-globals` write owner-only files on Unix, including when replacing an earlier export. - **What's new dialog and update flow.** The dialog closes with Escape, and blocked browser storage no longer breaks the update check or the automatic install. - **Manual request names.** The collection tree and starred list keep the saved name until you save a rename. - **Environment actions dismiss normally.** Click outside the menu or press Escape to close it. The editor no longer duplicates environment switching with an **In use** or **Use environment** button; use the top bar or sidebar. - **Selectable chat text on macOS and Linux.** AI request messages can be selected and copied again. - **Primary icon buttons.** The icon on buttons such as **Send** in an AI request is no longer faint grey. - **Dropdowns near the window edge** open towards the left instead of running off-screen. - **No browser tooltips.** The grey hover tooltips are gone throughout the app. - **No browser tooltips on folding arrows in code editors.** The arrows that fold and unfold lines no longer show a native "Fold line" tooltip. - **Desktop scrollbars.** Transparent tracks and inset handles keep scrollbars from ending in a visible strip at panel edges. - **Consistent add and close icons.** Plus and close icons have the same size and stroke across tabs, dialogs, panels, and the sidebar. - **Collection test hint.** The Tests tab now says the collection script runs after each request's own tests. - **Status bar alignment.** The branch name and the change count of the Git status sit on one baseline. - **Globals Secret button.** Its highlight covers the whole word. - **Storage indicator.** The local storage label and badge are centred and fit inside the status bar. ## Older releases Notes for 2.0.0 through 2.6.1 are in [Release notes 2.x](https://kurlo.dev/changelog/v2/), and notes for 1.0.0 through 1.8.1 are in [Release notes 1.x](https://kurlo.dev/changelog/v1/).