Insomnia CLI for coding agents

When a coding agent edits an API definition or works in a repository that contains Insomnia API tests, you can give it a shell command to check that work. Insomnia’s command-line tool, called Inso, lints API specifications and runs Insomnia test suites and request collections. A command-line interface, or CLI, lets a person or agent run a program by typing commands in a shell.

Inso does not need a special agent integration for these tasks. The agent runs the same commands a developer would, then uses the command’s findings and exit status to report whether the check passed. The Inso CLI documentation describes its commands and use in development workflows.

What Inso checks

Inso can lint an API specification, which describes an API’s endpoints and the shape of its requests and responses. Linting checks the specification against configured rules and reports findings. Inso can also run Insomnia test suites and request collections. Those tests send API requests, so their effects depend on the requests and the server they target. Insomnia describes API testing with collections and suites, and its CI documentation covers running checks in automated pipelines.

For an agent reviewing a changed API definition, start with inso lint spec. It works against local project files and does not send requests to an API. Use inso run test or inso run collection when you intend to exercise an API; point those tests at a suitable test environment and inspect their requests before running them.

Install and lint a local spec

The documented npm installation command is:

npm install -g insomnia-inso
inso --version

The installation contacts the npm package registry and installs Inso globally for the current environment. The version command confirms that the shell can find the executable. See the Inso CLI CI instructions for setup in automated workflows.

From a repository that contains an Insomnia project and API specification, run:

cd /path/to/repository
inso lint spec

Replace /path/to/repository with the local path to the project. Inso prints lint findings when it finds them and returns an exit status that automation can use to distinguish success from failure. The command does not change the specification or contact an API. This example uses no output-format flag; an agent should report the command’s actual findings and status rather than infer a result or parse an assumed JSON format.

For multiple specifications or a named target, check the installed command’s syntax with inso lint spec --help. The exact target depends on the names and files in your repository.

Give the agent a bounded task

A useful prompt tells the agent what to check, where to run the command, and what not to do:

Review the API specification changed in this repository. Do not edit files or send API requests. From the repository root, run inso lint spec and summarize the reported findings and exit status.

This lets the agent check the specification using local project files without giving it credentials or asking it to test a live service. CI runs software checks automatically, and Inso can run as part of those checks without someone at the keyboard. Inso disables prompts and provides exit codes that mark a job as passing or failing, as described in Kong’s CI guidance.

If you later ask the agent to run a test suite or collection, treat that as a separate action: those commands make network requests, and the configured requests may change server data. API authentication belongs in the Insomnia environment or the approved secret mechanism for your CI environment. Do not paste tokens into the agent prompt. A local lint run needs no API credentials because it does not call the API.

Know what linting cannot confirm

A clean lint result says that the specification passed the rules Inso applied. It does not prove that a deployed API behaves as the specification says. To check behavior, run a test suite against an appropriate API environment and review the requests it will send. Inso supports those test and collection commands, but the agent needs the relevant Insomnia files in the project and an appropriate API environment to target.

The commands here follow Insomnia’s documentation; they have not been installed or tested for this article. An agent can use Inso to run the same API check from the shell again. The repository’s rules, tests, and environment determine what the result means.