Mockoon CLI for coding agents

When a coding agent needs to build or test an API client without calling a live service, Mockoon CLI can run a local mock API from a Mockoon data file or an OpenAPI specification. A mock API returns responses defined for development and testing, so the client can work against predictable endpoints while the real service remains untouched.

Mockoon CLI is a command-line tool written for Node.js. An agent with shell access can start the mock server, send it requests, and read its responses. Besides start, the CLI has import and export commands that convert between OpenAPI files and Mockoon data files. The Mockoon CLI README describes its supported inputs and commands.

Install the CLI

Install Node.js first, then install Mockoon CLI from npm:

npm install -g @mockoon/cli

The Mockoon CLI page shows the same package name, and the README lists the Node.js versions the CLI has been tested on. Installing the package contacts the npm registry, where npm packages are stored. After installation, you can run a mock from a local data file without Mockoon account credentials or credentials for the API being simulated.

Keep API keys and other secrets out of the agent prompt. For a local mock that does not use authenticated real services, the agent needs only the local file path and the mock’s route details.

Start a local mock

For a small client task, use a Mockoon environment data file that already defines the route and response the client expects. You can create or export that file with Mockoon’s desktop application, then ask the agent to run the CLI against it.

mockoon-cli start --data ./mockoon-data.json --port YOUR_PORT

Here, ./mockoon-data.json is a placeholder path: replace it with the path to your exported Mockoon data file. Replace YOUR_PORT with an available local port. The --port value overrides the port saved in the data file. The command starts a server on your machine in the foreground; it does not deploy the mock to a shared or public host.

In a second terminal, send a request to the route defined in the file:

curl -i http://localhost:YOUR_PORT/your-route

Replace /your-route with the route path configured in the Mockoon environment. That route’s settings determine the response status and headers, as well as its body. The exact output depends on the file. The README lists the start command options, including --data and --port. Stop the server with Ctrl+C when the agent finishes.

This example keeps the request on the local machine as long as the environment does not use proxy mode. With proxy mode on, Mockoon forwards requests that do not match a declared route to the target URL set in the file. Add --proxy disabled to the start command to turn proxying off for that run. Each running mock also has an admin API at /mockoon-admin/, protected by a bearer token that the CLI prints at startup when you don’t set one. --disable-admin-api turns it off.

Use it for client work

A useful task is asking an agent to implement a client method against a local response before the real API is available. The mock can return the expected success response, and route response rules can return error responses for chosen requests. Mockoon also has a templating system for dynamic mock data.

A realistic prompt is:

Start Mockoon CLI with ./mockoon-data.json on an available local port. Read the route configured for the customer lookup, then implement the client method and add a test that calls the local mock. Do not call the production API or change the mock data file. Report the test command and any failure.

This prompt keeps the agent’s work local and explains what to do. The agent can inspect the data file, start the mock, and run the project’s tests. The CLI itself does not verify that the mock matches a live service contract, so the developer still needs to confirm that the configured route and response reflect the API behavior the client must support.

Know what the CLI covers

Mockoon CLI runs mock APIs from local data or OpenAPI definitions. Mockoon notes that OpenAPI files do not map to all of its features. For templating and response rules, run the Mockoon data file itself. Mockoon also documents how to run it in continuous integration (CI), where code changes trigger automated checks, through a GitHub Action. Tests can use it to get predictable API responses without depending on a live endpoint.

mockoon-cli validate --data ./mockoon-data.json checks a data file against Mockoon’s schema. It does not check OpenAPI files. The CLI also runs the behavior described by its input: if the data file contains an incorrect route or response, the local server will reproduce that incorrect setup. Review the file and test the client against the cases it defines.