Imposter: Scriptable, multipurpose mock server

June 12, 2026 · View on GitHub

Reliable, scriptable and extensible mock server for REST APIs, OpenAPI (and Swagger) specifications, SOAP/WSDL Web Services, Salesforce and HBase APIs.

This project is the CLI tool for the Imposter mock engine.

Stand up a live mock from an OpenAPI spec in one command:

$ imposter up -s

found 1 OpenAPI spec(s)
starting server on port 8080...
mock server up and running at http://localhost:8080

You now have a live mock of your OpenAPI spec running on localhost.

Record HTTP exchanges by proxying a real endpoint, then replay them as a mock:

$ imposter proxy https://example.com

starting proxy on port 8080
wrote response file /users.json for request GET /users
wrote config file example.com-config.yaml

Run imposter up to start the mock you just recorded.

Or scaffold a mock straight from an OpenAPI/WSDL file:

$ imposter scaffold

found 1 OpenAPI spec(s)
generated 1 resources from spec
wrote Imposter config: /Users/mary/example/petstore-config.yaml

Run imposter up to start your mock.

Features

Stand up mocks in place of real systems, locally or in CI
Turn an OpenAPI/Swagger or WSDL file into a working mock — even before the real API exists
Decouple integration tests from cloud and back-end dependencies
Validate requests against an OpenAPI specification
Capture data and serve conditional, templated responses
Store data for later retrieval or validation
Proxy and record an existing endpoint to replay it as a mock
Drive responses with JavaScript, Groovy, or your own plugin

Install

You'll need Docker, or alternatively a JVM (JVM engine) or no extra runtime at all (Native engine).

Homebrew

brew tap imposter-project/imposter
brew trust imposter-project/imposter
brew install imposter

Shell script (macOS and Linux)

curl -L https://raw.githubusercontent.com/imposter-project/imposter-cli/main/install/install_imposter.sh | bash -

For other platforms or manual installs, see Installation.

Common commands

Each command has full help via imposter <command> --help.

Command	What it does
`imposter up [DIR]`	Start a live mock from Imposter config in `DIR` (defaults to current directory). Add `-s` to scaffold first, or `-d` to background it (use `--id-file` to record its ID).
`imposter scaffold [DIR]`	Generate Imposter config from any OpenAPI/Swagger or WSDL files in `DIR`.
`imposter proxy URL`	Forward traffic to `URL` and record each exchange to disk as a replayable mock. Add `--insecure` to skip TLS verification.
`imposter down ID`	Stop the mock with the given ID (see `imposter ls`), or read the ID from a file with `--id-file`. `-a` / `--all` stops every managed mock across all engine types.
`imposter list`	List running mocks and their health across all engine types. `-t` filters by engine type; `-qx` makes a tidy healthcheck.
`imposter bundle [DIR]`	Bundle config and engine into a Docker image or Lambda zip.
`imposter doctor`	Check that you have at least one engine ready to run.
`imposter engine pull` / `engine list`	Manage cached engine binaries and images.
`imposter plugin install` / `list` / `uninstall`	Manage engine plugins.
`imposter remote ...`	Configure and deploy to a remote Imposter target.
`imposter workspace ...`	Manage workspaces for remote deployments.
`imposter version`	Print CLI and engine version info.

Healthcheck

imposter list -qx

Exits 0 if at least one mock is running and healthy, non-zero otherwise.

Logging

Default log level is debug. Override with the LOG_LEVEL environment variable:

export LOG_LEVEL=info

Or per invocation:

imposter up --log-level trace

Configuration

See Configuration for the CLI config file, environment variables, and engine-specific settings.

Other deeper guides:

About Imposter

Imposter is a mock server for REST APIs, OpenAPI/Swagger, SOAP/WSDL, Salesforce and HBase.

📖 Full user documentation

Imposter logo

Contributing

Suggestions and improvements to the CLI or its documentation are welcome. Please raise pull requests targeting the main branch.