# Insomnia API Client — User Guide

Insomnia is an open-source, cross-platform **API client** for designing, debugging, testing, and mocking APIs. With a single desktop application you can send requests over REST, GraphQL, WebSockets, Server-Sent Events (SSE), gRPC, and Socket.IO, design APIs against the OpenAPI specification, organize work into collections, run collections and test suites, and ship the same workflows into CI/CD with the companion **`inso`** command-line tool.

This guide is written for people who *use* Insomnia: developers debugging an API, QA engineers building test suites, API designers writing OpenAPI specs, and platform teams wiring Insomnia into a pipeline. It covers the desktop app and the `inso` CLI end to end — every protocol, every storage mode, the scripting API, and the troubleshooting you will actually hit.

> [!NOTE]
> Insomnia is built by **Kong** and is licensed under Apache-2.0. The desktop app is free to use without an account through the local **Scratch Pad**, and most everyday features are available on the free plan. Some collaboration features (organizations, Git Sync, SSO) require an account or a paid subscription. This guide notes where an account is required.

---

## 1. Quick Start

This section gets you from a fresh install to your first successful request in a few minutes.

### 1.1 Install and launch

1. Download Insomnia for macOS, Windows, or Linux from [insomnia.rest](https://insomnia.rest).
2. Install and launch the app.
3. On first launch you can either **log in / create a free account** or click **Use the local Scratch Pad** to start immediately with no account.

> [!TIP]
> Choose **Scratch Pad** if you just want to try the app or work entirely offline. Everything you do in the Scratch Pad is stored locally and never leaves your machine. You can sign in later without losing your work.

### 1.2 Send your first request

1. Create a **Collection** (the container for related requests).
2. Click **+** and choose **HTTP Request**.
3. In the URL bar, pick the method (`GET`) and type a URL, for example `https://httpbin.org/get`.
4. Press **Send** (or `Ctrl/Cmd + Enter`).
5. The response appears in the right-hand pane: status code, time, size, headers, and a formatted body.

```text
200 OK · 142 ms · 318 B
{
  "args": {},
  "headers": { "Host": "httpbin.org", ... },
  "url": "https://httpbin.org/get"
}
```

> [!TIP]
> The URL bar accepts a full `curl` command or a raw URL with query parameters — paste either and Insomnia parses it into a request.

### 1.3 The three things to learn next

| Concept | Why it matters | Section |
|---|---|---|
| **Environments** | Store base URLs, tokens, and variables so requests stay portable | [§4](#4-environments-and-variables) |
| **Storage backend** | Decide whether data lives locally, in Git, or in the cloud | [§3](#3-projects-collections-and-storage) |
| **Collection Runner / `inso`** | Run many requests or tests at once, in the app or in CI | [§7](#7-running-collections-and-tests) |

---

## 2. Installation and Requirements

### 2.1 Desktop application

Insomnia ships as a packaged desktop application for the three major platforms. Install it the same way you install any other desktop app for your OS (drag to Applications on macOS, run the installer on Windows, use the AppImage/`.deb`/`.rpm` on Linux).

| Platform | Notes |
|---|---|
| **macOS** | Universal build; signed and notarized. |
| **Windows** | Squirrel/NSIS installer. A portable build is also available (`PORTABLE_EXECUTABLE_DIR`). |
| **Linux** | AppImage, `.deb`, `.rpm`, and Snap. |

> [!NOTE]
> Insomnia uses the native **libcurl** library to make HTTP requests. This is what gives it deep control over TLS, redirects, proxies, and HTTP versions — but it also means the desktop app, not a browser engine, is doing the networking.

### 2.2 The `inso` CLI

`inso` is a standalone command-line companion that runs your Insomnia collections, tests, and linting outside the desktop app (typically in CI). It is distributed as:

- a self-contained **binary** (no Node.js required to run it), and
- an npm-installable package for Node environments.

=== "npx (no install)"

    ```bash
    npx insomnia-inso --version
    ```

=== "Global npm install"

    ```bash
    npm install -g insomnia-inso
    inso --version
    ```

=== "Standalone binary"

    ```bash
    # Download the binary for your platform, then:
    ./inso --version
    ```

> [!IMPORTANT]
> `inso` reads the **same data** your desktop app uses. It can locate your locally installed Insomnia data automatically, or you can point it at a Git project folder or an exported `.yaml`/`.db.json` file with `-w, --workingDir`. See [§8](#8-the-inso-cli).

### 2.3 System notes

- **Large responses** (~20 MB and above) can be memory-heavy and may slow or crash the app on low-RAM machines. Prefer downloading large response bodies to a file.
- Insomnia checks for updates automatically by default; you can change or disable this in **Preferences** (see [§9.4](#94-updates)).

---

## 3. Projects, Collections, and Storage

Insomnia organizes your work in a hierarchy. Understanding it is the key to everything else.

```text
Organization                (a workspace for you or your team — requires an account for teams)
└── Project                 (a storage-scoped grouping)
    ├── Collection           (a set of requests + folders, for debugging/testing)
    └── Design Document       (an OpenAPI spec + its generated request collection)
```

- A **Request** is a single call (HTTP, GraphQL, gRPC, WebSocket, SSE, Socket.IO).
- A **Folder** (request group) nests requests and can carry its own environment, auth, and scripts that child requests inherit.
- A **Collection** is the top-level container you send and run.
- A **Design Document** holds an OpenAPI specification you author, lint, and preview.

### 3.1 Storage backends

Every project chooses how its data is stored. This is one of Insomnia's defining features — you decide per project whether data ever touches the cloud.

| Backend | What it does | Account needed? |
|---|---|---|
| **Local Vault** | 100% local storage on your machine — collections, specs, and every other resource stay on disk | No (works in Scratch Pad too) |
| **Git Sync** | Stores project data in **any** third-party Git repository (GitHub, GitLab, Bitbucket, self-hosted) without going through Insomnia's cloud | Account (paid feature) |
| **Cloud Sync** | Stores data in Insomnia's cloud for real-time collaboration, optionally **end-to-end encrypted (E2EE)** | Account |

> [!TIP]
> You can mix backends across projects. Keep a sensitive project **Local Vault** or **Git Sync** while collaborating on others via **Cloud Sync** — there is no all-or-nothing choice.

> [!IMPORTANT]
> **Private Environments**: regardless of the storage backend you pick, you can mark an environment as private so its configuration is *always stored locally and never synced to the cloud*. Use this for secrets you never want to leave your machine.

### 3.2 The Scratch Pad

The **Scratch Pad** is a special always-local workspace available without an account. It is the fastest way to start and the right choice when you cannot send data to any cloud. You can export from the Scratch Pad at any time.

> [!WARNING]
> Some users have reported that exporting the **Scratch Pad** to a YAML file can produce an empty file in certain builds (community issue [#9509](https://github.com/Kong/insomnia/issues/9509)). If an export looks empty, see [§11 Troubleshooting](#11-troubleshooting).

---

## 4. Environments and Variables

Environments make requests portable: instead of hard-coding `https://api.example.com` and a bearer token in every request, you store them once and reference them with **template tags**.

### 4.1 Environment levels

Insomnia resolves variables from several scopes, from broadest to narrowest:

| Scope | Where it lives | Typical use |
|---|---|---|
| **Global environment** | Shared across collections | Org-wide constants |
| **Base environment** | The collection's default values | Default base URL, shared IDs |
| **Sub-environment** | A named override of the base (e.g. *Production*, *Staging*) | Per-stage values |
| **Folder environment** | Attached to a folder | Values for a group of requests |
| **Iteration data** | Rows of data fed to the Collection Runner | Data-driven runs |

Switch the active sub-environment with the **environment picker** in the sidebar, or with the keyboard shortcut for *Switch environment menu*.

### 4.2 Using variables

Reference any variable with the double-brace template syntax:

```text
{{ _.base_url }}/users/{{ _.user_id }}
```

Type `{{` in any URL, header, query, or body field (these fields are full editors) and Insomnia autocompletes available variables.

> [!TIP]
> Insomnia's template engine is **Nunjucks**-based. Beyond plain variables, it supports **template tags** — dynamic values like timestamps, UUIDs, base64/hashing, prompts, and *response* tags that pull a value out of another request's response. Turn on **Nunjucks power-user mode** in Preferences to edit raw template syntax.

### 4.3 The Vault (encrypted secrets)

For secrets you do not want stored in plain text, use the **Vault**. The Vault is protected by a **Vault Key**:

- Create a vault key the first time you store a secret.
- The key can be saved locally and (optionally) in your OS secret manager so you do not retype it.
- You can reset, re-validate, or clear the vault key from the app.

> [!CAUTION]
> By default, vault secrets are **not** exposed to pre-request/after-response scripts. To read vault values from scripts you must explicitly enable **`enableVaultInScripts`** in Preferences. Leave it off unless a script genuinely needs a secret.

---

## 5. Building and Sending Requests

This is the core of the **Debug** screen. Insomnia supports many protocols; each has a tailored editor.

### 5.1 HTTP / REST requests

For a standard HTTP request you control:

- **Method and URL** — including query parameters (edit them inline or in the **Query** tab; a bulk editor is available).
- **Body** — choose a body type: JSON, XML, form URL-encoded, multipart form, GraphQL, raw text, binary file, or none. The editor formats and lints JSON/XML/GraphQL.
- **Headers** — add headers individually or with the **bulk header editor**. Default headers can be applied automatically.
- **Authentication** — see [§6](#6-authentication).
- **Docs** — a Markdown description tab for documenting the request.
- **Scripts** — pre-request and after-response scripts (see [§10](#10-scripting)).
- **Settings** — per-request overrides such as following redirects, SSL validation, and timeout.

Send with **Send** or `Ctrl/Cmd + Enter`. The response pane shows the body (with preview modes for HTML, JSON, images, and PDFs), headers, cookies, the **timeline** (the raw libcurl exchange), and timing.

> [!TIP]
> Every URL/header/body field is a **CodeMirror** editor, so you get syntax highlighting, autocompletion of variables and template tags, and inline linting. The downside: very large fields and responses are heavier than plain text inputs.

### 5.2 Response history and previews

Insomnia keeps a **response history** per request (default: the last 20 responses, configurable via `maxHistoryResponses`). You can:

- re-open any past response,
- preview as raw, pretty, HTML, or image,
- save the response body to a file,
- delete a single response or clear all history for a request.

> [!WARNING]
> "Save to File" has been reported to create an **empty file** in some cases (community issue [#9879](https://github.com/Kong/insomnia/issues/9879)). If you hit this, try saving from the raw preview, or export the response another way.

### 5.3 GraphQL requests

Choose **GraphQL** as the body type to get:

- a GraphQL query editor with schema-aware autocompletion,
- a **variables** editor,
- the built-in **GraphQL Explorer** for browsing the schema,
- automatic schema introspection from the endpoint.

### 5.4 gRPC requests

Create a **gRPC Request** to call gRPC services:

- import a `.proto` file or a proto directory, or use **server reflection** to discover methods,
- pick a method from the method dropdown,
- send **unary**, **server-streaming**, **client-streaming**, and **bidirectional-streaming** calls,
- edit request messages as JSON.

### 5.5 WebSocket requests

Create a **WebSocket Request** to open a persistent connection:

- connect to a `ws://` or `wss://` URL,
- send messages (text/JSON/binary) interactively,
- view the live event stream of sent and received messages,
- attach headers and authentication to the handshake.

> [!NOTE]
> Path parameters and variables are applied to most request types, but a known issue ([#9947](https://github.com/Kong/insomnia/issues/9947)) reports they may not be applied in WebSocket connections — substitute values manually if a `{{ }}` tag does not resolve in a WebSocket URL.

### 5.6 Server-Sent Events (SSE) and Socket.IO

- **SSE**: open an event-stream endpoint and watch events arrive in real time.
- **Socket.IO**: connect to a Socket.IO server, emit events, and subscribe to channels.

### 5.7 Cookies

Each workspace has a **Cookie Jar**. Insomnia stores cookies returned by responses and sends them automatically on subsequent matching requests. You can view, add, edit, and delete cookies in the cookie manager.

---

## 6. Authentication

Insomnia supports a broad set of auth schemes on the **Auth** tab of a request (or inherited from a parent folder/collection). Configure once on a folder and child requests inherit it.

| Auth type | Notes |
|---|---|
| **None** | No auth header added |
| **Basic** | Username + password |
| **Bearer Token** | `Authorization: Bearer <token>` |
| **API Key** | Custom header or query parameter |
| **OAuth 1.0** | Full OAuth 1.0a signing |
| **OAuth 2.0** | Authorization Code, Client Credentials, Password, Implicit grants; tokens are fetched and refreshed; session can be cleared on restart |
| **AWS IAM v4** | AWS Signature v4 signing |
| **Hawk** | Hawk authentication |
| **ASAP** | Atlassian ASAP (JWT) |
| **Microsoft NTLM** | NTLM auth |
| **Netrc** | Credentials from a `.netrc` file |

> [!TIP]
> OAuth 2.0 token state is stored per request. If you want a clean token on every app start, keep **`clearOAuth2SessionOnRestart`** enabled (it is on by default).

### 6.1 Client and CA certificates

Per workspace you can configure:

- **Client certificates** (mutual TLS): attach a PEM/PFX certificate + key, scoped to a host.
- **CA certificates**: provide a custom CA bundle so Insomnia trusts an internal/self-signed authority.

> [!NOTE]
> Authenticating with a company CA certificate has tripped some users up (community issue [#10024](https://github.com/Kong/insomnia/issues/10024)). Make sure the certificate host matches the request host and that the CA is added at the **workspace** level. See [§11](#11-troubleshooting).

---

## 7. Running Collections and Tests

Insomnia can execute many requests at once, both interactively (the **Collection Runner**) and as automated **unit tests**.

### 7.1 The Collection Runner

Open the **Runner** from a collection to:

- select which requests (or folders) to run and in what order,
- set an **iteration count** to repeat the run,
- supply **iteration data** (a JSON or CSV file) so each iteration uses different values — true data-driven testing,
- add a **delay** between requests,
- choose the active environment,
- view per-request results, test outcomes, and timing.

> [!TIP]
> Iteration data columns become variables for that iteration. A CSV with a `user_id` header lets `{{ _.user_id }}` resolve to a different value on each pass.

### 7.2 Unit test suites

The **Test** screen lets you write **test suites** containing JavaScript tests that send requests and assert on the responses using a Chai-style `expect` API. You can:

- create multiple test suites per collection,
- write tests that call a request by name/ID and assert on status, headers, body, and timing,
- run a single test, a suite, or **all** suites,
- view pass/fail results with execution time.

```javascript
// Inside a unit test
const response = await insomnia.send();
expect(response.status).to.equal(200);
expect(response.headers.get('content-type')).to.match(/json/);
```

### 7.3 Mock servers

Insomnia can **mock** an API for you. Create a **Mock Server** (cloud-hosted or self-hosted) and define **mock routes** that return canned responses. You can generate a request collection that targets the mock, so consumers can develop against the API before the backend exists.

---

## 8. Designing APIs (OpenAPI)

A **Design Document** is a first-class OpenAPI editor.

- Author your spec in the native OpenAPI editor with autocompletion.
- See a **visual preview** of the API as you type.
- **Lint** the spec against rules using **Spectral** (the same engine `inso lint` uses). Errors and warnings appear inline.
- Provide a custom **ruleset** (`.spectral.yaml`) to enforce your organization's API standards.
- **Generate a request collection** directly from the spec so you can immediately exercise the endpoints you designed.

> [!TIP]
> Designing and debugging live in the same project. Generate a collection from your spec, debug against a mock or a real server, and keep the spec as the source of truth.

---

## 9. Preferences and Settings

Open **Preferences** (gear icon, or the *Show general preferences* shortcut). Settings apply app-wide. The most useful ones:

### 9.1 Request behavior

| Setting | Default | What it does |
|---|---|---|
| `followRedirects` | `true` | Follow HTTP 3xx redirects automatically |
| `maxRedirects` | `10` | Cap on redirects followed (`-1` style limits apply per request) |
| `timeout` | `30000` ms | Request timeout; `0` disables |
| `validateSSL` | `true` | Verify TLS certificates |
| `validateAuthSSL` | `true` | Verify TLS for the auth/token endpoints |
| `preferredHttpVersion` | `default` | Force `V1_0`, `V1_1`, `V2_0`, `V2PriorKnowledge`, `v3`, or let libcurl negotiate |
| `maxHistoryResponses` | `20` | How many past responses to keep per request |
| `maxTimelineDataSizeKB` | `10` | Cap on timeline capture size |

### 9.2 Proxy

| Setting | Default | What it does |
|---|---|---|
| `proxyEnabled` | `false` | Route requests through a proxy |
| `httpProxy` | `''` | Proxy URL for HTTP |
| `httpsProxy` | `''` | Proxy URL for HTTPS |
| `noProxy` | `''` | Comma-separated hosts that bypass the proxy |

### 9.3 Editor and appearance

| Setting | Default | What it does |
|---|---|---|
| `theme` / `lightTheme` / `darkTheme` | app defaults | Color theme; `autoDetectColorScheme` follows the OS |
| `fontSize` | `13` | UI font size |
| `editorFontSize` | `11` | Code editor font size |
| `editorIndentSize` | `2` | Spaces per indent |
| `editorIndentWithTabs` | `true` | Indent with tabs |
| `editorLineWrapping` | `true` | Wrap long lines |
| `editorKeyMap` | `default` | `default`, `vim`, `emacs`, or `sublime` |
| `fontVariantLigatures` | `false` | Enable font ligatures |
| `autoHideMenuBar` | `false` | Hide the menu bar (Windows/Linux) |

### 9.4 Updates

| Setting | Default | What it does |
|---|---|---|
| `updateAutomatically` | `true` | Download and install updates automatically |
| `updateChannel` | `stable` | `stable` or `beta` |
| `disableUpdateNotification` | `false` | Suppress the "update available" notice |

### 9.5 Privacy and security

| Setting | Default | What it does |
|---|---|---|
| `enableAnalytics` | `true` | Send anonymous usage data |
| `showPasswords` | `false` | Reveal masked secret fields |
| `scriptSandboxEnabled` | `true` | Run scripts in a sandbox |
| `scriptStrictModeEnabled` | `true` | Run scripts in strict mode |
| `enableVaultInScripts` | `false` | Allow scripts to read vault secrets |
| `saveVaultKeyLocally` | `true` | Persist the vault key on disk |
| `saveVaultKeyToOSSecretManager` | `true` | Store the vault key in the OS keychain |

> [!TIP]
> To work fully offline and privately, set storage to **Local Vault**, disable `enableAnalytics`, and disable `updateAutomatically`.

### 9.6 Keyboard shortcuts

Every shortcut is rebindable under **Preferences → Keyboard**. Frequently used defaults:

| Action | Shortcut id |
|---|---|
| Send request | `request_send` |
| Quick switch request | `request_quickSwitch` |
| Focus URL bar | `request_focusUrl` |
| New HTTP request | `request_createHTTP` |
| Show request options | `request_showOptions` |
| Toggle sidebar | `sidebar_toggle` |
| Focus sidebar filter | `sidebar_focusFilter` |
| Show environment editor | `environment_showEditor` |
| Switch environment menu | `environment_showSwitchMenu` |
| Beautify request body | `beautifyRequestBody` |
| Show cookies editor | `showCookiesEditor` |
| Next / previous tab | `tab_nextTab` / `tab_previousTab` |
| Reopen closed tab | `tab_reopenClosedTab` |
| Open request in new tab | `request_openInNewTab` |
| Show general preferences | `preferences_showGeneral` |
| Show keyboard shortcuts | `preferences_showKeyboardShortcuts` |
| Reload plugins | `plugin_reload` |

---

## 10. Scripting

Insomnia lets you run JavaScript **before** a request (pre-request) and **after** a response (after-response). Scripts get a rich `insomnia` object for reading and mutating the request, environment, and response.

### 10.1 Where scripts run

- **Pre-request script**: runs before the request is sent. Use it to set headers, compute signatures, or fetch a token.
- **After-response script**: runs once the response arrives. Use it to extract values, set variables, or assert in tests.

Scripts run in a **sandbox** (`scriptSandboxEnabled`) under **strict mode** (`scriptStrictModeEnabled`) by default.

### 10.2 The `insomnia` object

The scripting API is exposed as `insomnia`. Core members:

| Member | Purpose |
|---|---|
| `insomnia.request` | The outgoing request — read/modify URL, method, headers, body, auth |
| `insomnia.response` | The response (after-response scripts only) — status, headers, body, time |
| `insomnia.environment` | Get/set active environment variables |
| `insomnia.baseEnvironment` / `insomnia.collectionVariables` | The collection's base variables |
| `insomnia.variables` | Unified variable access across scopes (`globalVars`, `collectionVars`, `environmentVars`, `iterationDataVars`, `localVars`) |
| `insomnia.cookies` | The cookie jar for the request |
| `insomnia.info` | Request metadata (id, name, iteration info) |
| `insomnia.execution` | Control flow, including `setNextRequest()` for the runner |
| `insomnia.vault` | Vault secrets (only when `enableVaultInScripts` is on) |
| `insomnia.test(name, fn)` | Define a test assertion |
| `insomnia.expect(value)` | Chai-style assertions |
| `insomnia.sendRequest(...)` | Send an ad-hoc request from within a script |

Each variable scope supports `has()`, `get()`, `set()`, `unset()`, `clear()`, `replaceIn()`, and `toObject()`.

```javascript
// Pre-request: add a timestamp header
insomnia.request.addHeader({ key: 'X-Timestamp', value: String(Date.now()) });

// After-response: capture a token into the environment
const body = insomnia.response.json();
insomnia.environment.set('access_token', body.access_token);

// Assert in a test
insomnia.test('status is 200', () => {
  insomnia.expect(insomnia.response.code).to.equal(200);
});

// Control runner flow
insomnia.execution.setNextRequest('Get Profile');
```

> [!NOTE]
> The scripting object is named `insomnia`. Insomnia's scripting model is designed to be familiar to users of other API clients, but document and test against the `insomnia.*` names shown above — they are the verified surface.

### 10.3 Data folder access

Scripts (and the runner) can read and write files only within folders you allow. In the desktop app this is governed by your settings (`dataFolders`); with the CLI you pass `-f, --dataFolders`. This is a safety boundary — keep it narrow.

---

## 11. The `inso` CLI

`inso` runs your Insomnia collections, tests, and linting from a terminal — ideal for CI/CD. It reads the **same data** as the app.

### 11.1 How `inso` finds your data

`inso` resolves data in this order:

1. `-w, --workingDir <dir>` if provided — point it at an `.insomnia` folder, a Git project folder, a `*.db.json`, or an exported `export.yaml`.
2. Otherwise, your **locally installed Insomnia data** directory.

You identify what to run by an **id** (e.g. `wrk_...`, `spc_...`, `uts_...`) or, in interactive mode, by picking from a prompt. In CI use `--ci` to disable all prompts.

### 11.2 Global options

These apply to every command:

| Option | Description |
|---|---|
| `-w, --workingDir <dir>` | Working directory/file: `.insomnia` folder, `*.db.json`, or `export.yaml` |
| `--verbose` | Show additional logs (request timelines, traces) |
| `--ci` | Run in CI mode — disables all interactive prompts |
| `--config <path>` | Path to a config file (`.insorc`) |
| `--printOptions` | Print the resolved options and exit-relevant config |
| `-v, --version` | Print the CLI version |
| `-h, --help` | Show help for any command |

### 11.3 `inso run collection`

Run a request collection.

```bash
inso run collection -w ./my-project wrk_abc123 \
  --env production \
  --reporter spec
```

| Option | Description |
|---|---|
| `[identifier]` | Workspace/collection id (positional) |
| `-t, --requestNamePattern <regex>` | Only run requests whose name matches the regex |
| `-i, --item <requestid>` | Run a specific request or folder id (repeatable; order is preserved) |
| `-e, --env <identifier>` | Environment to use |
| `-g, --globals <identifier>` | Global environment (file path or id) |
| `--delay-request <ms>` | Delay between requests (default `0`) |
| `--requestTimeout <ms>` | Per-request timeout (defaults to user settings) |
| `--env-var <key=value>` | Override an environment variable (repeatable) |
| `-n, --iteration-count <count>` | Repeat the run N times (default `1`) |
| `-d, --iteration-data <path/url>` | JSON or CSV data file for data-driven runs |
| `-r, --reporter <reporter>` | Test reporter (e.g. `spec`, `min`, `dot`, `tap`, `progress`, `list`) |
| `-b, --bail` | Stop after the first non-200 response |
| `--disableCertValidation` | Skip TLS certificate validation |
| `--httpProxy <proxy>` / `--httpsProxy <proxy>` | Proxy URLs |
| `--noProxy <list>` | Comma-separated hosts bypassing the proxy |
| `-f, --dataFolders [dirs...]` | Folders scripts/requests may read/write |
| `--output <file>` | Write a JSON result report to a file |
| `--includeFullData <type>` | Include full request/response/env data in the report: `redact` or `plaintext` |
| `--acceptRisk` | Accept the security warning when writing full data to a file |

> [!CAUTION]
> `--includeFullData=plaintext` writes request bodies, responses, **and environment values (including secrets)** to the report file. `inso` shows a security prompt unless you pass `--acceptRisk`. Prefer `redact` and never commit these reports.

### 11.4 `inso run test`

Run unit test suites.

```bash
inso run test -w ./my-project uts_abc123 --env staging --reporter min
```

| Option | Description |
|---|---|
| `[identifier]` | Test suite id or API Spec id (positional) |
| `-e, --env <identifier>` | Environment to use |
| `-t, --testNamePattern <regex>` | Run tests matching the regex |
| `-r, --reporter <reporter>` | Reporter (default `spec`) |
| `-b, --bail` | Stop after the first test failure |
| `--keepFile` | Keep the generated test file (debugging) |
| `--requestTimeout <ms>` | Per-request timeout |
| `-k, --disableCertValidation` | Skip TLS validation |
| `--httpProxy` / `--httpsProxy` / `--noProxy` | Proxy options |
| `-f, --dataFolders [dirs...]` | Allowed data folders |

### 11.5 `inso lint spec`

Lint an OpenAPI specification with Spectral.

```bash
# Lint a spec by id from a project
inso lint spec -w ./my-project spc_abc123

# Lint a spec file directly
inso lint spec ./openapi.yaml

# Use a custom ruleset
inso lint spec ./openapi.yaml --ruleset ./.spectral.yaml
```

| Option | Description |
|---|---|
| `[identifier]` | API Spec id or a file path |
| `-r, --ruleset <path>` | Path to a Spectral ruleset; overrides the default OAS ruleset and any folder ruleset |

> [!TIP]
> If you do not pass `--ruleset`, `inso` looks for a `.spectral.yml`/`.spectral.yaml` next to the spec. Keep your org's ruleset in the repo so the app and CLI lint identically.

### 11.6 `inso export spec`

Export an OpenAPI specification to a file or stdout.

```bash
inso export spec spc_abc123 -w ./my-project -o ./dist/openapi.yaml --skipAnnotations
```

| Option | Description |
|---|---|
| `[identifier]` | API Spec id |
| `-o, --output <path>` | Write the spec to a file (otherwise prints to stdout) |
| `-s, --skipAnnotations` | Remove all `x-kong-*` annotations from the output |

### 11.7 `inso script` and `inso generate-docs`

- **`inso script <script-name>`** — run a named script defined in your `.insorc` config file. Each script entry must itself start with `inso`. This lets you alias common invocations.
- **`inso generate-docs`** — print the CLI's command documentation.

### 11.8 The `.insorc` config file

`inso` reads a config file (default name `.insorc`, in YAML or JSON) from the working/current directory, or from `--config`. It can pre-set global options and define reusable scripts:

```yaml
# .insorc.yaml
options:
  workingDir: ./my-project
  ci: true
scripts:
  lintSpec: inso lint spec spc_abc123
  exportSpec: inso export spec spc_abc123 -o ./dist/openapi.yaml
```

Run a script with:

```bash
inso script lintSpec
```

### 11.9 Exit codes and proxies

- `inso` exits **0** on success and **1** on failure (failed test, lint error, missing data) — perfect for CI gating.
- Proxy environment variables are respected automatically: `HTTP_PROXY`/`http_proxy`, `HTTPS_PROXY`/`https_proxy`, and `NO_PROXY`/`no_proxy`. Flags (`--httpProxy`, etc.) override them.
- Telemetry can be disabled with `INSO_TELEMETRY_DISABLED=1` (or by disabling analytics in the app, which `inso` reads from your local settings).

### 11.10 CI example (GitHub Actions)

```yaml
name: API checks
on: [push]
jobs:
  inso:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Lint the API spec
        run: npx insomnia-inso lint spec ./openapi.yaml --ruleset ./.spectral.yaml
      - name: Run the test suite
        run: npx insomnia-inso run test -w . uts_abc123 --ci --reporter min
```

---

## 12. Plugins

Insomnia is extensible through **plugins** installed from the [Plugin Hub](https://insomnia.rest/plugins/). Plugins can add template tags, request/response hooks, themes, and more.

- Install, enable, disable, and configure plugins under **Preferences → Plugins**.
- Reload plugins without restarting using the `plugin_reload` shortcut.
- Plugins are stored in your plugin path (`pluginPath`) and can be individually disabled via `pluginConfig`.

> [!NOTE]
> Some capabilities ship as bundled first-party plugins (for example AI and external-vault integrations). These appear automatically; third-party plugins are what you install from the Hub.

---

## 13. Importing and Exporting

### 13.1 Import

Insomnia imports from many sources. Use **Import** and either scan a file or paste a URL/clipboard:

| Source | Notes |
|---|---|
| **Insomnia** v1–v5 exports | Native format (YAML/JSON) |
| **Postman** collections & environments | Collection v2 + environment files |
| **OpenAPI / Swagger** | OpenAPI 3 and Swagger 2 specs become a design + collection |
| **cURL** | A single `curl` command becomes a request |
| **WSDL** | SOAP service definitions |
| **HAR** | HTTP Archive captures |

### 13.2 Export

Export a collection, design document, or your whole workspace to Insomnia's YAML format. You can also export an OpenAPI spec from a design document (in the app or with `inso export spec`).

> [!WARNING]
> Exports can contain secrets stored in environments. Review what you are exporting before sharing the file, and prefer **Private Environments** for values that must never leave your machine.

---

## 14. Syncing and Collaboration

### 14.1 Git Sync

Connect a project to a Git repository to version your API work with your code.

- Clone an existing repo or initialize sync on a project.
- **Stage**, **commit**, **push**, **pull/fetch**, view **diffs** and **history**, and manage **branches** — all from inside Insomnia.
- Authenticate with GitHub/GitLab (OAuth) or a personal access token / credentials.

> [!IMPORTANT]
> Git Sync stores data as files in **your** repository — Insomnia's cloud is not involved. This is the right choice for teams that must keep API definitions in their own version control.

### 14.2 Cloud Sync

For real-time collaboration, Cloud Sync stores project data in Insomnia's cloud with branch/snapshot semantics (create snapshot, pull, push, restore, rollback, merge branches). It can be **end-to-end encrypted**.

### 14.3 Known sync caveat

> [!WARNING]
> Clearing the local cache while using Git/Cloud sync has been reported to make collections temporarily disappear ([#10003](https://github.com/Kong/insomnia/issues/10003)). Push/commit your work before clearing caches, and use **pull/fetch** to restore from the remote if collections vanish locally.

---

## 15. AI and MCP features

Recent Insomnia versions include AI-assisted and **Model Context Protocol (MCP)** capabilities:

- **AI-generated commit messages** for sync commits.
- An **MCP** request type and workspace MCP view, letting Insomnia act as an MCP client to language-model tooling.

These features may require an account and an enabled AI plugin. They are optional — none of the core request/test/design workflows depend on them.

---

## 16. Troubleshooting

Each entry uses the format **Symptom → Cause → Solution → Prevention**.

### Error: `Specification content not found using API spec id`

- **Cause:** `inso` could not find a spec with that id in the working directory.
- **Solution:** Verify the id (it starts with `spc_`) and that `-w` points at the right `.insomnia` folder, Git project, or export file. List specs by running the command interactively (without `--ci`) to pick from a prompt.
- **Prevention:** Keep a `.insorc` with the correct `workingDir` and spec ids.

### Error: `No environment identified; cannot run requests without a valid environment.`

- **Cause:** No environment was selected and `inso` could not infer one.
- **Solution:** Pass `-e, --env <id-or-name>`. In CI, also pass `--ci` and ensure the environment exists in the data.
- **Prevention:** Name environments consistently across stages and reference them by name in `.insorc`.

### Error: `CSV file must contain at least two rows with first row as variable names`

- **Cause:** The `--iteration-data` CSV has only a header (or is empty).
- **Solution:** Provide a header row plus at least one data row. For JSON, supply an array of key/value objects.
- **Prevention:** Validate the data file before a CI run.

### Error: `Uploaded file is unsupported`

- **Cause:** `--iteration-data` points at a file that is not `.json` or `.csv`.
- **Solution:** Convert the data to JSON (array of objects) or CSV.
- **Prevention:** Stick to JSON/CSV for runner data.

### Error: `Environment variable DEFAULT_APP_NAME is not set.`

- **Cause:** `inso` could not determine the app data directory because `DEFAULT_APP_NAME` is unset in the environment.
- **Solution:** Run `inso` from a normal shell where it can resolve the Insomnia data dir, or pass `-w` to point at data explicitly so it does not need the default app dir.
- **Prevention:** Prefer `-w` in CI rather than relying on a locally installed app.

### Symptom: "Save to File" creates an empty file

- **Cause:** Known issue in some builds ([#9879](https://github.com/Kong/insomnia/issues/9879), [#9509](https://github.com/Kong/insomnia/issues/9509) for Scratch Pad YAML).
- **Solution:** Save from the **raw** response preview, or export via **Export** / `inso`. Update to the latest version.
- **Prevention:** Track the linked issues; keep Insomnia updated.

### Symptom: Cannot authenticate with a company CA certificate

- **Cause:** The CA is not registered at the workspace level, or the certificate host does not match the request host ([#10024](https://github.com/Kong/insomnia/issues/10024)).
- **Solution:** Add the CA certificate under the **workspace** CA settings and confirm the host matches. For mTLS, also add the client certificate scoped to the same host.
- **Prevention:** Keep a documented CA/client-cert setup per environment.

### Symptom: `{{ }}` variables not applied in WebSocket URLs

- **Cause:** Known issue ([#9947](https://github.com/Kong/insomnia/issues/9947)).
- **Solution:** Substitute the value directly in the WebSocket URL until the fix ships.
- **Prevention:** Track the issue; test WebSocket URLs after editing variables.

### Symptom: App is slow or crashes on a large response

- **Cause:** Loading very large responses (~20 MB+) is memory-heavy.
- **Solution:** Save the response to a file instead of previewing; close other tabs.
- **Prevention:** Avoid previewing multi-MB bodies; use streaming endpoints where possible.

### Symptom: Collections disappear after clearing cache with sync on

- **Cause:** Known sync/cache interaction ([#10003](https://github.com/Kong/insomnia/issues/10003)).
- **Solution:** **Pull/fetch** from the remote to restore. Avoid clearing caches with unsynced changes.
- **Prevention:** Commit/push before clearing caches.

### Symptom: Linux app crashes on launch with `write EPIPE`

- **Cause:** Reported on some Linux desktop-file launches ([#9951](https://github.com/Kong/insomnia/issues/9951)).
- **Solution:** Launch from a terminal to see logs; try the AppImage build; update to the latest version.
- **Prevention:** Track the issue; keep the app updated.

### Symptom: Windows 12.6.0 won't open

- **Cause:** Reported startup issue ([#9959](https://github.com/Kong/insomnia/issues/9959)).
- **Solution:** Reinstall, or roll back to a known-good version while the fix lands.
- **Prevention:** Stay on the `stable` update channel for production work.

---

## 17. FAQ

**Q: Do I need an account to use Insomnia?**
No. Use the local **Scratch Pad** with no account. An account unlocks cloud collaboration, organizations, Git Sync, and SSO; most everyday debugging/testing works without one.

**Q: Can I keep all my data off the cloud?**
Yes. Choose **Local Vault** or **Git Sync** storage per project, and mark sensitive environments as **Private** so they never sync.

**Q: Which protocols does Insomnia support?**
REST/HTTP, GraphQL, gRPC (unary and streaming), WebSockets, Server-Sent Events, and Socket.IO.

**Q: Is `inso` separate from the desktop app?**
Yes — it is a standalone CLI that reads the same data. Install it independently for CI; you do not need the desktop app on a build agent.

**Q: How do I run my Insomnia tests in CI?**
Use `inso run test` (or `inso run collection`) with `--ci` and a `--reporter`. It exits non-zero on failure so the pipeline fails. See [§11.10](#1110-ci-example-github-actions).

**Q: How do I lint my OpenAPI spec the same way in CI and the app?**
Both use **Spectral**. Keep a `.spectral.yaml` ruleset in your repo; the app's design linter and `inso lint spec --ruleset` will agree.

**Q: Where does Insomnia store my data on disk?**
In the OS app-data directory: `~/Library/Application Support/Insomnia` (macOS), `%APPDATA%\Insomnia` (Windows), or `$XDG_DATA_HOME`/`~/.config` (Linux). `inso` uses the same location.

**Q: How do I migrate from Postman?**
Use **Import** and select your Postman collection (v2) and environment exports. Insomnia maps them to collections and environments.

**Q: Can scripts read my vault secrets?**
Only if you enable **`enableVaultInScripts`**. It is off by default for safety.

**Q: How do I disable telemetry?**
Turn off **`enableAnalytics`** in Preferences (the CLI reads this), or set `INSO_TELEMETRY_DISABLED=1` for the CLI.

**Q: How do I force HTTP/2 or HTTP/1.1?**
Set **`preferredHttpVersion`** in Preferences, or override per request in request settings.

**Q: Can I use Vim or Emacs keybindings in the editors?**
Yes — set **`editorKeyMap`** to `vim`, `emacs`, or `sublime`.

**Q: My request needs a client certificate. Where do I add it?**
Under the **workspace** certificate settings: add a client certificate (mTLS) scoped to the host, and a CA certificate if the server uses an internal authority.

**Q: What's the difference between the Collection Runner and unit tests?**
The Runner executes a sequence of requests (optionally data-driven) and shows results interactively. Unit tests are reusable assertions you write once and run repeatedly (in the app or via `inso run test`).

---

_Generated June 2026 from Kong/insomnia at bece185. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._