Mock server commands
This topic covers mock server commands for the Postman CLI.
Many of these commands work with both local mocks and cloud mocks. Local mocks are identified by a file path, and cloud mocks are identified by a mock ID. When you pass a mock ID, the command acts on the mock in the Postman cloud, which requires you to sign in with the postman login command or pass an --api-key.
postman mock run
You can use the postman mock run command to start a mock, which is a code-based JavaScript API simulator. Provide a path to a local mock, or a cloud mock’s ID. When you provide a cloud mock ID, the CLI fetches that mock from Postman and runs it on your machine. This command doesn’t operate a mock server hosted in the Postman Cloud. To publish a cloud mock to a hosted mock server, use the postman mock deploy command.
A manifest file, in JSON or YAML format, lets you configure details like the mock’s port number, name, script, and more. The mock runs on the specified port until you stop it. If the specified port is already in use, the mock falls back to an available port assigned by the OS. Make sure you also have a JavaScript file with an HTTP server that sets the request and example response for simulating real API behavior.
You can add the command to your CI/CD script to start a mock as a dependency for your application or test suite. Once running, your service or external tests can send requests to it as if it were a real API. This enables you to simulate API behavior for testing and development.
Learn more at Build API mocks with JavaScript.
To run a collection against a mock, use the --mock option with the postman collection run command.
Usage
A cloud mock’s ID, or a path to a local mock. The path can be a manifest file (JSON or YAML), a mock directory such as postman/mocks/<slug>, or a .js handler script.
Options
Specifies the path to an environment file (JSON or YAML) loaded into pm.environment for the mock’s scripts. The file can be a Postman environment (with a values array) or a flat map of key: value pairs.
Specifies the path to a globals file (JSON or YAML) loaded into pm.globals for the mock’s scripts.
The port the mock listens on. Pass auto for an OS-assigned ephemeral port. By default, the mock uses the port from its configuration, falling back to an ephemeral port if that port is busy.
Your Postman API key, used to authenticate when you run a cloud mock by its ID. Defaults to your postman login session.
Example
postman mock generate
You can use the postman mock generate command to generate a runnable mock from a Postman Collection or an OpenAPI 3.0 or 3.1 specification. The command auto-detects the source type. It accepts a collection in v2.0, v2.1, or v3 format, either as a file or a Git-native v3 collection directory, or an OpenAPI specification file.
If you run the command without a source, it generates a sample mock with a GET /health endpoint that you can use as a starting point.
After you generate a mock, start it with the postman mock run command. To create the mock in a Postman workspace, use the --workspace option.
Learn more at Build API mocks with JavaScript.
Usage
The path to the source collection or OpenAPI specification file. The source type is auto-detected. If omitted, the command generates a sample mock.
Options
The output directory for the generated mock. You can’t use this option with --update.
A display name for the generated mock.
The port the mock listens on.
Overwrites the config.yaml or default.js file in the output directory if it already exists.
Updates an existing mock in place from the source. Provide the path to its config.yaml file, or the directory that contains it. This regenerates the default scenario handler and preserves the existing name, port, and scenarios. You can’t use this option with --output.
Creates the mock in the specified Postman workspace.
Your Postman API key, used to authenticate with the --workspace option. Defaults to your postman login session.
Always exits with code 0, even on failure.
Examples
postman mock get
Use the postman mock get command to show a mock’s details. Provide the path to a mock, or a cloud mock’s ID. A path shows the mock’s details and run status. A cloud mock ID shows the mock’s cloud details, including its deployed mock servers and their IDs.
Usage
A cloud mock’s ID, or the path to a mock (or a directory that contains one).
Options
Outputs the mock details in JSON format instead of a table.
Your Postman API key, used to authenticate when you get a cloud mock by its ID. Defaults to your postman login session.
Examples
postman mock list
Use the postman mock list command to list mocks. By default, it lists the cloud mocks in the workspace linked in your .postman/resources.yaml file, and errors if no workspace is linked. Provide a path to list local mocks under a directory instead, or use the --workspace option to list a specific workspace’s cloud mocks.
Usage
A directory to search for local mocks. Provide it to list local mocks instead of the linked workspace’s cloud mocks. You can’t combine it with --workspace.
Options
Lists the cloud mocks in the specified workspace, instead of the workspace linked in .postman/resources.yaml. You can’t combine it with a path.
Your Postman API key, used to authenticate with the --workspace option. Defaults to your postman login session.
Outputs the mock list in JSON format instead of a table.
Examples
postman mock delete
Use the postman mock delete command to permanently remove a mock. Provide the path to a mock, or a cloud mock’s ID. A path removes the mock from your machine. A cloud mock ID removes it from the Postman Cloud.
Usage
A cloud mock’s ID, or the path to a mock (or a directory that contains one).
Options
Skips the confirmation prompt.
Your Postman API key, used to authenticate when you delete a cloud mock by its ID. Defaults to your postman login session.
Examples
postman mock deploy
You can use the postman mock deploy command to publish a cloud mock to a mock server, making it available at a hosted URL. This command works with cloud mocks only, so provide the mock’s ID rather than a local path.
Run the command interactively to set the mock server’s name, slug, and visibility, or pass those as options to deploy from a script. New mock servers are private by default. To call a private mock server, send a valid Postman API key in the x-api-key header. After a private deploy, the CLI prints an example request showing this.
The postman mock deploy command is available on Postman Solo, Team, and Enterprise plans. For more information, see the pricing page.
To use this command, sign in to Postman with the postman login command, or pass an --api-key.
Usage
The ID of the cloud mock to deploy.
Options
A display name for the mock server.
The subdomain for the mock server’s URL, such as the my-mock in https://my-mock.mock.<team-domain>.postman.dev.
Makes the mock server public. Mock servers are private by default.
Redeploys the mock server automatically whenever the cloud mock changes. Without this option, the mock server isn’t redeployed automatically.
The ID of the workspace that contains the mock. Defaults to the workspace in your .postman/resources.yaml file.
Accepts the defaults and skips all prompts. The mock server is private with auto-deploy off.
Your Postman API key. Use it to authenticate instead of signing in with postman login.
Example
postman mock log
You can use the postman mock log command to browse a deployed mock server’s request and response history, with the newest entries first. Provide the mock server’s ID, which you can find with the postman mock get command.
By default, the command streams the entries interactively. Use the --json option for machine-readable output.
The postman mock log command is available on Postman Solo, Team, and Enterprise plans. For more information, see the pricing page.
To use this command, sign in to Postman with the postman login command, or pass an --api-key.
Usage
The ID of the deployed mock server whose logs you want to view.
Options
Filters entries by HTTP method, such as GET or POST.
Filters entries by response status. Accepts an exact code, such as 404, or a class range, such as 5xx.
Filters entries by request path. Supports the * and ? wildcards.
Shows only entries newer than the given duration, so --since 7d shows the last seven days. Use a whole number with a unit of ms, s, m, h, or d, such as 30m, 2h, or 7d.
Shows only entries older than the given duration, so --until 2h hides the last two hours. Combine it with --since to bound both ends of a window. For example, --since 14d --until 7d shows the seven days that ended a week ago. Use a whole number with a unit of ms, s, m, h, or d, such as 30m, 2h, or 7d.
The maximum number of entries to show.
Outputs the logs in JSON format instead of streaming them interactively.
Your Postman API key. Use it to authenticate instead of signing in with postman login.