You need a fake API to build against. The backend isn’t ready, or the third-party service is rate-limited, or you just want your tests to run without hitting a live server. The usual answer is a mock. The question is how you stand one up.
You can click through a GUI to define routes and canned responses. That’s fine once. But a mock you build by hand in a desktop app is hard to reproduce, hard to version, and impossible for CI or an AI coding agent to recreate on its own. A mock you define from the command line is different. It’s a command in a script, a step in a pipeline, a line an agent can run. What you type, a machine can type too.
This guide covers two routes. First, the general open-source path: single-binary mock servers you run straight from a file, so a spec or a JSON file becomes a live endpoint in one command. Then the Apidog CLI path, which works differently and is worth understanding on its own terms. If you want the landscape of options first, our roundup of the best API mock tools and the REST API mocking tools guide both give you the wider view.
The general route: run a mock server from a file
The classic CLI mock is a small binary you point at a file. Give it a spec or a data file, and it serves a real HTTP endpoint on a local port. No project, no login, no account. These tools do one thing: turn a file into a fake API you can call. Three cover almost every case.
Prism: serve an OpenAPI spec
If you already have an OpenAPI file, Prism from Stoplight is the lowest-effort mock you can run. It reads your paths, examples, and schemas, then serves responses that match the contract.
npx @stoplight/prism-cli mock ./openapi.yaml
That starts a server on http://127.0.0.1:4010 with every operation in your spec wired up. Prism returns the example you defined for a response, or generates a valid random one from the schema if you left it out. It also validates incoming requests against the spec, so a malformed call gets a proper 422 instead of a silent pass. Call it to check it’s alive:
curl http://127.0.0.1:4010/orders/123
Prism is stateless, so a POST doesn’t persist anything. That’s the point when you want the mock to stay honest to the contract. For a global install, run npm install -g @stoplight/prism-cli and drop the npx.
Mockoon CLI: run a data file headless
Mockoon CLI runs a mock from a data file, either one you exported from the free Mockoon desktop app or a plain OpenAPI spec. The desktop app lets you build routes visually; the CLI runs that same environment headless in CI or on a server.
npx @mockoon/cli start --data ./env.json
Point --data at a Mockoon environment file or an OpenAPI JSON/YAML file and it serves immediately, defaulting to port 3000. Add --port to change it. If the data file came from an older Mockoon version, the CLI migrates it in memory without touching the original. Install it globally with npm install -g @mockoon/cli for a persistent mockoon-cli command. This is a good fit when you want richer, hand-tuned routes than a bare spec gives you and still want them to run without a GUI. A lightweight mock server for a RESTful API often lands here.
json-server: fake a REST API from JSON
When you don’t have a spec yet, json-server is the fastest path. You write a plain JSON file describing your data, and it builds a full REST API around it.
npx json-server db.json
Given a db.json with a posts array, that serves http://localhost:3000/posts with real GET, POST, PUT, PATCH, and DELETE. A POST actually adds a record and writes it back to the file, so you get stateful behavior for free, which Prism won’t give you. You also get filtering, sorting, and pagination through query params. Install globally with npm install -g json-server if you want it always on your PATH.
That’s the open route. Each tool is a single binary, runs from one file, and needs nothing else. The trade-off is that each one is its own island. The mock lives apart from your real design, your tests, and your docs, and you keep the files and the running processes in sync yourself. If you need exact request matching or replay, MockServer and WireMock go deeper, at the cost of a Java runtime.
The Apidog CLI route: import the spec, script the expectations
Apidog mocks differently, and getting this right saves you confusion. The apidog CLI does not start a local mock server from a file. There’s no apidog mock ./openapi.yaml. Instead, Apidog hosts the mock for you, and the CLI is how you feed it a spec and script custom responses.
One honest note first. Apidog isn’t open source; it’s a commercial product with a free tier. What that free tier plus the CLI buys you is an integrated project, so the mock, the design, and the tests share one source of truth instead of three separate files and three separate processes. If a throwaway mock from one file is all you need, a lighter tool wins. If your mock should stay in step with your actual API as it changes, read on.
Install and authenticate first (the Apidog CLI installation guide covers token setup):
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Import a spec to get hosted smart mocks
The first step is to get your API into a project. Import an OpenAPI file, and Apidog generates a mock URL for every endpoint automatically.
apidog import --project <PROJECT_ID> --format openapi --file ./openapi.json
This is where Apidog differs from Prism and json-server. You don’t run a server; the import gives you a hosted smart mock for each operation. Smart mock reads your schema’s field types and names, so an email field returns a plausible email and a createdAt returns a real-looking timestamp, not a random string. apidog import also accepts Swagger 2.0, Postman, and Apidog formats, so an existing definition becomes live mocks in one command.
Script custom responses with apidog mock
Auto-generated mocks cover the common case. When you need a specific response for a specific request, say a 200 for one user ID and a 404 for another, you add a mock expectation. This is what the apidog mock command group manages, and it’s CRUD on those expectations, not a server you start.
apidog mock --help
apidog mock list --project <PROJECT_ID>
apidog mock list --project <PROJECT_ID> --http-api-id <ENDPOINT_ID>
Listing returns structured JSON, so you can pipe it through jq to find an expectation’s ID and feed it to the next command. To read, change, or remove one:
apidog mock get --project <PROJECT_ID>
apidog mock update --project <PROJECT_ID> --file ./mock.json
apidog mock delete --project <PROJECT_ID>
The create and update subcommands take a --file describing the expectation. Get the shape right before you write it, covered next.
Validate the expectation file before you write it
Don’t hand-guess the JSON. The CLI ships a schema for every write, so you fetch the shape, fill it in, and validate before the real write. A malformed expectation fails fast instead of landing silently.
apidog cli-schema get mock-create
apidog cli-schema validate mock-create --file ./mock.json
apidog mock create --project <PROJECT_ID> --file ./mock.json
Fetch the schema, write your mock.json to match, validate it, then create. If validate returns a non-zero exit, the pipeline stops before a bad file reaches your project. Run the same three steps for updates with the mock-update schema key. Every command returns JSON with an agentHints.nextSteps block that tells you, or an agent, what to run next, which is what makes this flow usable by AI coding tools and not just humans. The complete Apidog CLI guide maps the rest of the command groups.
Wiring it into CI
Both routes fit a pipeline because every command has an exit code and text output. A server-based mock and an integration test in the same job might look like this:
# start Prism in the background, then run tests against it
npx @stoplight/prism-cli mock ./openapi.yaml &
PRISM_PID=$!
npm test
kill $PRISM_PID
The Apidog flow is different in shape: there’s no local process to start and stop, because the mock is hosted. You validate and apply expectations as a setup step, and your tests hit the hosted mock URL directly.
# ensure the expectation is well-formed, then apply it
apidog cli-schema validate mock-create --file ./mock.json
apidog mock create --project <PROJECT_ID> --file ./mock.json
Either way, no one clicks a button. That’s the whole reason to mock from the CLI: a spec-first team, a CI job, and an AI agent can all stand up the same fake API from the same commands.
Common snags
Expecting apidog mock to start a server. It won’t. There’s no apidog mock start, apidog mock serve, or apidog mock ./file.yaml. You apidog import a spec to get hosted mocks, and apidog mock manages the custom expectations on top of them. If you want a local process you launch from a file, that’s Prism, Mockoon CLI, or json-server.
Skipping the schema step on a write. apidog mock create and update take a --file, and a wrong shape fails or writes something you didn’t mean. Always run cli-schema get and cli-schema validate first. It’s two extra commands and it saves you a debugging session.
Prism looks empty because your spec is thin. Prism’s mock is only as good as your examples. If a response has no example and a vague schema, you get vague data. Add examples to the spec and the mock gets sharper.
Stateful expectations from a stateless tool. Prism and Apidog’s contract mocks don’t persist writes. If you need a POST then GET to return the new record, reach for json-server or an Apidog expectation that returns the shape you want.
Wrapping up
Mocking from the CLI turns a click-heavy chore into commands you can script, review, and hand to CI or an agent. The open route gives you single-binary servers you run from a file: Prism for an OpenAPI spec, Mockoon CLI for a headless data file, json-server for an instant REST API from JSON. The Apidog route works the other way; you import a spec once to get hosted smart mocks, then script custom responses with apidog mock and the cli-schema validate guard.
Pick by what you already have and where the mock needs to live. If you want a throwaway server from one file, the open tools are perfect. If you want the mock to stay in step with your design and tests in one project, Download Apidog, install the CLI, and stand up your mocks without touching a mouse.
