DEV Community

Cover image for What Is inso? The Insomnia CLI
Hassann
Hassann

Posted on • Originally published at apidog.com

What Is inso? The Insomnia CLI

If you have used the Insomnia API client, you already have a GUI for sending requests, designing OpenAPI specs, and writing tests. But GUI workflows stop at your machine. When you need the same tests in CI, or you want to lint a spec on every pull request, you need a terminal-friendly tool. That tool is inso.

Try Apidog today

This guide shows what inso is, how to install it, which commands you will use day to day, how it finds your specs and collections, and where its limits appear. By the end, you should know whether the inso CLI fits your workflow and what to use if it does not.

What is inso?

inso is the command-line companion to Insomnia, the open-source API client maintained by Kong. It makes three Insomnia workflows scriptable:

  • Running tests
  • Executing request collections
  • Linting API specifications

That makes it the bridge between Insomnia on your desktop and automated checks in CI/CD.

Insomnia inso CLI overview

The short version: inso lets you run your Insomnia work without opening Insomnia. You point it at a design document, test suite, or collection by name, and it executes against the same Insomnia project data.

Installing the inso CLI

You have a few supported installation paths. Pick the one that matches your environment.

Install with Homebrew

Homebrew is the simplest option on macOS and Linux:

brew install inso
Enter fullscreen mode Exit fullscreen mode

Install with Docker

Docker is usually the cleanest option for CI runners, where you do not want to manage a local toolchain:

docker pull kong/inso:latest
Enter fullscreen mode Exit fullscreen mode

Install from a direct download

Kong publishes Windows, Linux, and macOS zip archives on the inso CLI documentation site. This is useful when you want to pin a specific version in a build artifact or internal toolchain.

Historically, inso was also distributed on npm as insomnia-inso. That route still exists, but the documented and recommended paths are now Homebrew, Docker, and direct downloads. For new setups, prefer those.

Confirm the installation:

inso --version
Enter fullscreen mode Exit fullscreen mode

The core inso commands

inso has a small, focused command surface. These are the commands you are most likely to use in local automation and CI.

inso run test

Run a unit test suite created in Insomnia against a named environment:

inso run test "Payments API tests" --env "Staging"
Enter fullscreen mode Exit fullscreen mode

The test suite and environment are referenced by name, exactly as they appear in your Insomnia data.

If any assertion fails, inso run test exits with a non-zero status code. That makes it usable as a CI gate.

Example CI behavior:

inso run test "Payments API tests" --env "CI"

if [ $? -ne 0 ]; then
  echo "API tests failed"
  exit 1
fi
Enter fullscreen mode Exit fullscreen mode

inso run collection

Run every request in a collection in sequence:

inso run collection "Checkout flow" --env "Staging"
Enter fullscreen mode Exit fullscreen mode

This is the CLI equivalent of running a whole folder or collection from the UI. It is useful for smoke tests where you want to verify that a sequence of endpoints still responds as expected.

inso lint spec

Validate an OpenAPI design document:

inso lint spec "Orders API"
Enter fullscreen mode Exit fullscreen mode

Under the hood, inso lint spec uses Spectral, the open-source OpenAPI and JSON linter from Stoplight.

That is one of inso’s strongest use cases: you get rule-based OpenAPI linting with a mature ruleset, not just a shallow syntax check. If your team enforces API style guides on pull requests, this command is likely the main reason to use inso.

inso export spec

Export a design document to a file on disk:

inso export spec "Orders API" --output orders.yaml
Enter fullscreen mode Exit fullscreen mode

Use this when you need to:

  • Commit a generated snapshot
  • Feed the spec into another generator
  • Pass the spec to a tool that expects a plain YAML file
  • Archive the current state of an Insomnia design document

inso script

Run a named script defined in your Insomnia data:

inso script deploy-smoke --env env_9f2a
Enter fullscreen mode Exit fullscreen mode

This is the escape hatch for custom automation steps that are stored in your Insomnia project.

How inso finds your specs and collections

This is the part that often causes confusion: inso does not store your API data itself. It reads from one of two places.

1. A .insomnia directory in your working directory

This is what Insomnia’s Git Sync produces.

If your API project is committed to a repo with a .insomnia directory, inso can read directly from the checkout. This is the recommended pattern for CI.

Example repo structure:

api-project/
├── .insomnia/
├── README.md
└── .github/
    └── workflows/
        └── api-checks.yml
Enter fullscreen mode Exit fullscreen mode

Then run:

inso lint spec "Orders API" --workingDir .
Enter fullscreen mode Exit fullscreen mode

2. The local Insomnia application data directory

If Insomnia is installed on the machine, inso can read from the app’s local data directory.

This is convenient for local development, but it is not reliable in CI. A clean CI runner usually has no Insomnia app data.

Override the data source explicitly

You can point inso at a project directory:

inso lint spec "Orders API" --workingDir ./api-project
Enter fullscreen mode Exit fullscreen mode

Or point it at an exact source:

inso run test "Payments API tests" --src ./api-project/.insomnia
Enter fullscreen mode Exit fullscreen mode

The key mental model: inso resolves specs, suites, collections, and environments by name or ID against the data source it finds.

If the name is not present in the .insomnia directory or app data, inso cannot run it. There is no generic mode where you point inso at a loose OpenAPI file and say “test this” unless that file is part of an Insomnia project structure.

A minimal CI example

Here is a GitHub Actions workflow that lints a spec and runs a test suite on every push. It assumes the Git-synced .insomnia directory is committed to the repo.

name: API checks

on: [push]

jobs:
  inso:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Install inso
        run: |
          curl -sSL https://github.com/Kong/insomnia/releases/latest/download/inso-linux-x64.zip -o inso.zip
          unzip inso.zip && sudo mv inso /usr/local/bin/

      - name: Lint the spec
        run: inso lint spec "Orders API" --workingDir .

      - name: Run the test suite
        run: inso run test "Payments API tests" --env "CI" --workingDir .
Enter fullscreen mode Exit fullscreen mode

Because both commands exit non-zero on failure, a broken spec or failing assertion fails the job.

That is the main reason to move these checks out of the GUI: they become repeatable, reviewable, and enforceable in CI.

Honest limitations

inso is useful, but it has clear boundaries.

It is tied to Insomnia data

Your specs, collections, and test suites must live in an Insomnia project. They need to be available through either:

  • A Git-synced .insomnia directory
  • The installed Insomnia app’s local data

If your team does not use Insomnia as the source of truth, inso has nothing to operate on.

Names can be brittle

Most commands reference resources by name:

inso run test "Payments API tests" --env "Staging"
Enter fullscreen mode Exit fullscreen mode

That is readable, but it can break easily.

If someone renames the test suite in the UI, a CI job that hard-codes the old name will fail on the next run. Names also need to be unique enough to resolve cleanly.

The scope is intentionally narrow

inso focuses on a few verbs:

  • Run tests
  • Run collections
  • Lint specs
  • Export specs
  • Run scripts

It is not a full design, mock, documentation, and testing platform. For workflows outside those commands, you are either back in the Insomnia GUI or integrating other tools.

inso vs the integrated alternative

inso is a strong terminal companion when Insomnia is already your API client. The trade-off is that you are stitching together multiple pieces:

  • Insomnia for design and debugging
  • inso for CI execution
  • Spectral rules for linting
  • Separate tooling for mocks and docs

Apidog integrated API platform

Apidog takes the opposite approach. It puts design, mock, documentation, and testing in one platform, and its Apidog CLI runs your test scenarios and collections from the same source of truth, with data-driven testing, multiple reporter formats, and resource-and-branch-as-code.

To be fair, the Apidog CLI does not ship a standalone spec linter the way inso does with Spectral. If Spectral-style style-guide enforcement is your priority, inso has a real advantage there.

Where Apidog is different is integration. You are not gluing separate tools together for design, docs, mocks, and tests.

If you want to compare both options directly, see Apidog CLI vs inso (Insomnia CLI), or read the deeper background in what is inso (Insomnia CLI).

If you have decided inso is not the right home, the best inso alternative roundup and the migrate from inso to Apidog CLI guide walk through the move step by step.

For broader context on the GUI clients themselves, Apidog vs Insomnia and how to use Insomnia to test an API are good starting points.

You can download Apidog free if you want to compare the integrated approach side by side with your inso setup.

Top comments (0)