Postman CLI simulation commands (postman simulation)
Postman CLI simulation commands (postman simulation)
Postman Simulator is available on Postman Solo, Team, and Enterprise plans. For more information, see the pricing page.
This topic covers simulation commands for the Postman CLI.
A simulation groups several existing mocks as members and serves them behind one address. For each member mock, you select a scenario to simulate real-world conditions like latency, errors, and rate limits. To learn more about the concept, see Simulate API conditions with Postman Simulator.
A simulation lives as a .sim.yaml file in your repository, or as a simulation in a Postman Cloud workspace. postman simulation push uploads a local file to the cloud, and postman simulation deploy turns a cloud simulation into a live mock server with a public address.
To run a collection with a simulation, use the --simulate option with the postman collection run command.
postman simulation create
Scaffolds a .sim.yaml file that groups one or more existing mocks into a simulation. Pass each member mock with --mock, repeating the option to add more than one. A local mock path builds the simulation in your repository. A Postman mock ID creates it directly in a Postman Cloud workspace instead. Use one kind of reference or the other, not both in the same command.
Set a member’s address with <mockIdOrPath>=<routeKey>. If you omit the routeKey, the mock’s own name is used.
To create a simulation in a Postman Cloud workspace, sign in with the postman login command or pass --api-key.
Usage
Options
The name for the simulation.
A mock to include as a member. Repeatable. Set its address with <mockIdOrPath>=<routeKey>.
How callers reach each member mock. With path, the first path segment of the request selects the member. With header, callers select a member with the x-mock-slug header.
Where to save the simulation file in your repository, as a file or a folder.
Overwrites the simulation file if it already exists.
Creates the simulation in a Postman Cloud workspace, by ID, instead of your repository. Defaults to the workspace linked in .postman/resources.yaml.
Your Postman API key, used with --workspace. Defaults to your postman login session.
Examples
postman simulation list
Lists the simulations in your repository or a Postman Cloud workspace. Listing is local-first: without --workspace, it reads the postman/simulations directory in your repository. Pass --workspace to list a cloud workspace’s simulations instead.
To list a Postman Cloud workspace’s simulations, sign in with the postman login command or pass --api-key.
Usage
A directory to search for local simulations. Defaults to postman/simulations. You can’t combine it with --workspace.
Options
Lists the simulations in the specified Postman Cloud workspace, instead of your repository. You can’t combine it with a path.
Your Postman API key, used with --workspace. Defaults to your postman login session.
Prints the list as JSON for machine-readable output.
Examples
postman simulation get
Shows one simulation’s details: its member mocks, routing, each member’s scenario, and whether it’s deployed as a live mock server. Specify the simulation by its local .sim.yaml path, or by its ID if it lives in a Postman Cloud workspace.
To read a simulation by its cloud ID, sign in with the postman login command or pass --api-key.
Usage
A simulation’s local .sim.yaml path, or its ID if it lives in a Postman Cloud workspace.
Options
Your Postman API key, used when you read a simulation by its cloud ID. Defaults to your postman login session.
Prints the result as JSON for machine-readable output.
Examples
postman simulation run
Serves a simulation’s member mocks on one local port, routing each request to a member by its routeKey. Pass a local .sim.yaml path, or a Postman Cloud simulation ID to fetch and run the same simulation locally.
With path routing (the default), the first path segment of a request selects the member, so /payments/charges reaches the payments member as /charges. With header routing, callers select a member with the x-mock-slug: <routeKey> header.
Usage
A simulation’s local .sim.yaml path, or its ID if it lives in a Postman Cloud workspace.
Options
Path to a file of environment variables for the member mocks.
Path to a file of global variables for the member mocks.
Port to serve on. Pass auto to use a free port.
A dataset file or folder to load for pm.datasets. Repeatable.
Workspace to record start history against. Derived automatically from a simulation ID or your linked project, so this is only needed for an unlinked .sim.yaml path.
The simulation ID to record start history against, for a .sim.yaml path that isn’t linked to a cloud simulation (a local file has only a name on its own). Not needed when you run by simulation ID, or when the file is linked to a cloud simulation through postman simulation push.
Your Postman API key, used when you run by cloud ID. Defaults to your postman login session.
Doesn’t record this run in the simulation’s start history.
Live output format. auto prints human-readable logs. ndjson prints one JSON event per line, ending with a summary event, for CI or other non-interactive use.
The scenario each member mock serves, sent as both the pm-mock-scenario and x-mock-scenario headers.
Examples
Proxy mode
Pass --proxy to serve the member mocks behind a local HTTP/HTTPS forward proxy instead of one routed port. A repository under test can then point HTTP_PROXY/HTTPS_PROXY at the proxy and reach each member by hostname, without code changes. Proxy mode requires a simulation.yaml routing configuration file, which is a different file from the .sim.yaml used by the rest of this command.
Serves the member mocks behind a local forward proxy instead of one routed port. Records no start history.
Port for the proxy server. Distinct from --port, which is the routed (non-proxy) run’s own port.
Proxy request log format: text or json.
Also logs each response body, truncated. Buffers full responses in memory, so this is meant for temporary debugging rather than regular use.
Starts the proxy, probes each available HTTP client (fetch, undici, axios, node-fetch) to confirm it honors HTTP_PROXY/HTTPS_PROXY, then exits.
postman simulation push
Uploads a local simulation to a Postman Cloud workspace. The first push creates it there, and later pushes update it. Each member mock is pushed too, before the simulation that groups them.
To use this command, sign in with the postman login command or pass --api-key.
Usage
The local .sim.yaml file to upload.
Options
The Postman Cloud workspace to upload to, by ID. Defaults to the workspace linked in .postman/resources.yaml.
Your Postman API key. Defaults to your postman login session.
Examples
postman simulation deploy
Turns a simulation already in a Postman Cloud workspace into a live mock server that others can call over the internet. To upload a local simulation first, use postman simulation push.
To use this command, sign in with the postman login command or pass --api-key.
Usage
The ID of a simulation in a Postman Cloud workspace. Find it with postman simulation list.
Options
The Postman Cloud workspace that will own the server, by ID. Defaults to the workspace linked in .postman/resources.yaml.
A name for the mock server. You’re asked for one if you omit it.
A short label used in the server’s web address, such as my-sim. You’re asked for one if you omit it.
Requires a Postman API key to reach the server. Public by default.
Uses the defaults and skips all questions, including --private, so the server is public.
Your Postman API key. Defaults to your postman login session.
Examples
postman simulation delete
Permanently deletes a simulation, using its local .sim.yaml path or its Postman Cloud ID. This can’t be undone.
Deleting a cloud simulation also takes down its live mock server, if it was deployed. Deleting a local file removes only the .sim.yaml, leaving its member mocks untouched.
To delete a simulation by its cloud ID, sign in with the postman login command or pass --api-key.
Usage
A simulation’s local .sim.yaml path, or its ID if it lives in a Postman Cloud workspace.
Options
Deletes without asking for confirmation first.
Your Postman API key, used when you delete by cloud ID. Defaults to your postman login session.