Skip to main content
Recording gRPC APIs is currently only supported by the record-many command. See here for details.
The CLI offers a convenient way to record stubs from endpoints that are accessible from the computer running the CLI, but not accessible from the internet. Run:
At the end of your recording you will be asked to choose the Mock API to which you would like to save the recorded stubs, or create a new Mock API. If you know the ID of the Mock API you want to save to, you can skip the prompt by passing it as an argument:
where <mock_api_id> is the ID of the Mock API that should receive the recorded stubs. At present you can get that value by browsing into a Mock API at https://app.wiremock.cloud and extracting it from the URL - for instance in the URL https://app.wiremock.cloud/mock-apis/33eye3l9/stubs/1e0d7dc0-06a0-49a2-81a7-f5d6a40bfa3d, the ID is 33eye3l9 so you should record as so:
This will be made easier in future versions! The CLI will then run a proxy server bound to http://localhost:8000. Requests to this endpoint will be proxied to the endpoint you want to record from. When you have finished the journey you want to record, press <enter> to save the stubs to your Mock API in WireMock Cloud and the CLI will exit. You can specify the port the server should listen on using -p or --reverse-proxy-port:

​
Recording to a local mock API

As well as importing recorded stubs into a mock API in WireMock Cloud, the CLI can write them directly to a local mock API defined in your WireMock environment config file (wiremock.yaml). This is useful when you want to record stubs for use with the run command without needing a connection to WireMock Cloud, or without being logged in. To record into a specific local mock API, pass its service key using the local: prefix with the --to option:
where my-service is the key of the service as defined under services: in your wiremock.yaml file. The recorded stubs are written to that service’s stub-mappings.yaml file (e.g. .wiremock/my-service/stub-mappings.yaml). If you omit the service key and pass just --to=local, you will be prompted interactively to either choose an existing local mock API or create a new one:
When creating a new local mock API interactively, the CLI will add a new service entry to your wiremock.yaml file, assigning it the next available port and a path for its stub-mappings.yaml file.
Recording to a local mock API does not require you to be logged in to WireMock Cloud. The login step can be skipped entirely when using a local: destination.

​
Specifying the wiremock directory

By default the CLI looks for your wiremock.yaml file in a directory called .wiremock in the current working directory. If your config file lives elsewhere, point the CLI at it with the --wiremock-dir option:

​
Services without a path

A local service is normally configured with a path field pointing to the directory containing its stub-mappings.yaml file. If you select a service that has no path configured, the CLI will backfill one for you (creating an empty stub-mappings.yaml file at that path) so that recording can proceed. If the service is also missing a port, one will be assigned automatically.

​
Batching with a local destination

The batching options (--max-batch-requests and --max-batch-bytes) are supported when recording to a specific local mock API (--to=local:<service_key>). Stubs are flushed to the service’s local stub-mappings.yaml file in batches as the threshold is reached, rather than being held in memory until the end of the session. Batching is not supported with the interactive --to=local form (without a service key), because the destination service is only chosen after recording stops and so it is not known up front. If you need batching, specify the service key explicitly.
Local recording is currently only supported by the WireMock CLI’s record and record-many commands. It is not supported by the WireMock Runner’s record-many mode.

​
Importing recordings as you go along

By default, all the recorded requests are held in memory, and sent to the destination Mock API in WireMock Cloud at the end of the recording session. This may not be desirable; if you are doing a long recording session this may be prone to losing too much work. If you are doing a very large recording session the resulting import may be too large for WireMock Cloud (or other intermediate infrastructure) to cope. You may use the --max-batch-requests option to specify the maximum amount of requests to import into the destination Mock API in a single request. Given a max batch of N requests, an import to the mock API will occur for every N requests recorded. This requires you to specify the ID of the Mock API you want to save to via the --to option when launching the session. The --max-batch-bytes option is also available if you need control over the exact amount of bytes that can be sent in a single request to the destination Mock API. Given a max batch of N bytes, an import to the mock API will occur for every N bytes recorded. Note, if a single recorded request exceeds the maximum number of bytes, this request will still be sent (in a batch of one). Like max-batch-requests, this option requires you to provide a value to the --to option when launching the session.

​
Hostname rewriting

Often API responses contain absolute links and other content that refers to the domain name of the API’s origin. When recording an API this can be undesirable as the local proxy is different from the API being recorded, and thus any client following such a link would make its next request directly to the proxy target rather than the local CLI running the proxy. To remedy this issue, the Record command has hostname rewriting enabled by default, which will replace any instances of the proxy target’s domain name and port in the response headers or body with the local proxy’s domain name and port. If this is not the behaviour you want when recording, you can turn off hostname rewriting using the --no-rewrite-origin-hostname flag on the record command:

​
Advanced Recording

The WireMock CLI accepts a configuration file to control how stubs are recorded:
The format of this file is documented in the advanced recording configuration page.

​
Recording with Mutual TLS

If you need to record from an API that authenticates clients with mutual TLS, the CLI can present your private client certificate in one of two ways:

​
Via a PEM file

If you have a file containing a PEM encoded RSA private key and X509 certificate, you can provide it as so:
A PEM encoded file should look something like this:

​
Using a PKCS 12 certificate store

Keeping a private key in PEM format is a security risk, so we also support supplying your client certificate in a password protected PKCS 12 store as so:
You will be challenged for a password to decrypt the store and the private key. The same password must be able to decrypt both.

​
Non-interactive Recording Sessions

The WireMock CLI record command supports running in non-interactive mode, making it ideal for CI/CD pipelines and automated environments where user interaction is not possible or desired. See the Non-interactive Recording for more details.