Postman CLI simulation commands (postman simulation)
Postman CLI simulation commands (postman simulation)
Running simulations locally is available on all Postman plans. Deploying a simulation to the Postman Cloud is available on Solo, Team, and Enterprise plans only. For more information, see the pricing page.
This topic covers simulation commands for the Postman CLI.
A simulation groups several existing mocks of the services your app depends on and serves them together, so you can develop and test your service against the whole set. For each member mock, you select a scenario to apply 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 --simulation 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.
Alongside the .sim.yaml, the command writes a <name>.context.yaml record. The .sim.yaml says what the simulation is. The context record says what your code relies on about the services those mocks stand in for, and the evidence behind each assumption. The command generates it almost empty, as a template for whoever works on the simulation next, human or agent, to fill in as they establish things. No Postman CLI command writes entries for you.
The file is a single YAML document. simulation and generated record the name and the date the command wrote the file. purpose holds stands_in_for and unblocks, both null to begin with. assumptions holds one entry for each claim, each with an id, a status, a claim, a reason, a verification, a source, and an updated_at date. The status is supported, contradicted, unknown, or conflicting. fingerprints records the commit and Postman CLI version the claims were written against. A comment in the generated file explains each of these, with a worked example.
An assumption isn’t a description of the mock. It’s something your code is built on, recorded with the evidence for or against it. A filled-in record for a checkout path looks like this:
The second entry records an assumption that turned out to be false: the retry logic assumed a timeout meant no charge. The contradicted status keeps that finding next to the simulation that reproduces it.
If a <name>.context.yaml already exists, the command leaves it alone, so notes from earlier sessions aren’t lost. Renaming the simulation with postman simulation update renames its context file to match.
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. Inside a folder, the Postman CLI writes the file in a subfolder named for the simulation, as <slug>/<slug>.sim.yaml, matching the layout the Postman app writes. Simulation files saved directly in postman/simulations/ also run.
Overwrites the simulation file if it already exists.
Creates the simulation in a Postman Cloud workspace, by ID, instead of your repository. With --deploy, this is the workspace to deploy it to. Defaults to the workspace linked in .postman/resources.yaml.
Uploads the simulation and its member mocks to the Postman Cloud and deploys it to a live mock server, without asking any questions. The server is private by default, so callers must send a Postman API key.
Used with --deploy, lets anyone with the link reach the mock server instead of requiring a Postman API key.
Used with --deploy, the short label used in the mock server’s web address.
Used with --deploy, prints the live server’s details as machine-readable data instead of a summary.
Your Postman API key, used with --workspace, --deploy, or both. Defaults to your postman login session.
Prints the result as machine-readable data instead of a summary. With --deploy, the result is the live server’s details. If the command fails, it prints nothing on stdout and writes { "error": "<message>", "code": <exit code> } to stderr.
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 machine-readable data instead of a table. If the command fails, it prints nothing on stdout and writes { "error": "<message>", "code": <exit code> } to stderr.
Examples
postman simulation get
Shows one simulation’s details as a bold name followed by short lines of 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 details as machine-readable data instead of a summary. If the command fails, it prints nothing on stdout and writes { "error": "<message>", "code": <exit code> } to stderr.
Examples
postman simulation update
Changes a simulation in place: rename it, switch its routing, attach member mocks, or change a member’s address. Pass a local .sim.yaml path to update the file in your repository, or a Postman Cloud simulation ID to update it in the cloud.
To update a simulation by its cloud ID, sign in with the postman login command or pass --api-key.
Usage
The path to a local .sim.yaml file, or the ID of a simulation in a Postman Cloud workspace.
Options
Renames the simulation.
Switches how callers reach each member mock. With path, the first path segment selects the member. With header, callers select a member with the x-mock-slug header.
Attaches a mock to the simulation. Repeatable. Use a local mock path for a simulation in your repository, or a Postman mock ID for one in the Postman Cloud, never a mix of the two. Set the member’s address with <mockIdOrPath>=<routeKey>.
Changes a member mock’s address, for example ./postman/mocks/payments=payments. Repeatable.
Your Postman API key. Defaults to your postman login session.
Prints the update as machine-readable data instead of a table.
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.
A routed run never forwards a request. A call that no member models returns 501, or 404 with an Endpoint not defined body from a generated mock. To instead let calls for un-mocked hosts reach the real service, see Proxy mode.
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 bind an OS-assigned ephemeral port. If you omit this option, the command prefers the default port and falls back to a free port if that port is busy, so an omitted port isn’t guaranteed. To pin the port, pass a number. A port number you pass doesn’t fall back: if it’s busy, the command fails. To find the bound port, read the listening event from --output ndjson. The server binds 127.0.0.1 only, so a caller in a container or virtual machine can’t reach it.
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. Use auto to print human-readable logs. Use ndjson to print one JSON event per line, ending with a summary event, for CI or other non-interactive use. Each request event carries the status code, duration, response name and size, any applied scenarios, and any error.
Prints request and response headers and bodies for each request. By default, each request prints one line, plus any applied scenario or error. With --output ndjson, this adds the headers and bodies to each request event, along with an error stack when one is available.
Examples
Proxy mode
By default, a run serves the member mocks on one port, and callers reach each member by its routeKey. Proxy mode is for when your service can’t use that one address, because it calls each dependency by its real hostname and you can’t rewrite those URLs.
Pass --proxy and the Postman CLI starts a local HTTP/HTTPS forward proxy instead of one routed port. Point your service’s HTTP_PROXY and HTTPS_PROXY at the proxy, and all of its outbound requests flow through it with no change to your code. For each request, the proxy chooses between a mock and the real service by the request’s destination hostname:
- If the hostname matches a member mock’s
origin, the proxy routes the request to that mock. - If no member declares that hostname, the request passes through to the real service, unchanged.
This lets you mock the dependencies you’re working on and leave the rest real, without changing your service.
Requests that pass through the proxy reach real services and can change real data. Configure each member’s origin deliberately and use test environments.
An origin is the hostname, or list of hostnames, a member mock stands in for, such as api.example.com, declared in the .sim.yaml file. A member with no origin is never matched, so requests to its host reach the real service. The postman simulation create command copies origin from the mock’s own config.yaml, so adding an origin to a config.yaml doesn’t change a .sim.yaml file that already exists. To pick it up, edit the member in the .sim.yaml file or recreate the simulation.
Because the member mocks run on temporary ports, each mock’s own port is ignored. A member that doesn’t answer within 30 seconds returns 504, and one that can’t be reached returns 502. When the run ends, the Postman CLI prints the total, mocked, and passed-through request counts.
Passing any of the following options without --proxy is a usage error that exits with code 2, as is an unsupported --log-format.
Serves the member mocks behind a local forward proxy instead of one routed port. Records no start history.
Port for the proxy server. Pass auto to skip 7001 and bind a free port every time. When you omit this option, the command prefers 7001 and takes a free port when 7001 is busy. Read the bound port from the startup banner rather than assuming 7001. A port you pass by number exits with code 1 when it’s busy. Distinct from --port, which is the routed (non-proxy) run’s own port. The proxy binds 127.0.0.1, so point clients at that address instead of localhost. A client that resolves localhost to ::1 first can’t reach it.
The scenario each member mock serves, sent as both the pm-mock-scenario and x-mock-scenario headers. A member that defines no scenario by this name serves its default.
The session to select, sent as the x-mock-session header. Defaults to a generated ID.
Proxy request log format: text or json. Each line carries the method, host, path, destination (a routeKey, or passthrough), status, and duration. The json format adds a timestamp, the scenario, and the session.
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. You can’t combine --doctor with --lift.
Starts the command you give it behind the proxy, with HTTP_PROXY, HTTPS_PROXY, and NODE_EXTRA_CA_CERTS already set in its environment, instead of printing them for you to export by hand. The command runs as a child process, so the variables reach the code making the calls and not the CLI. Quote a command line that has arguments, such as "npm start". The proxy runs for as long as the command does, and the CLI exits with the command’s exit code.
For Node’s built-in fetch to use the proxy, the project needs undici installed, which the command preloads from the working directory. Without it, fetch calls reach the real service with no error, so use --doctor to confirm your client honors the proxy.
postman simulation stop
Stops a simulation that you started locally with postman simulation run, including --proxy runs. The command returns after the simulation and its member mocks exit and the port no longer accepts connections.
The simulation shuts down the same way as when you press Ctrl+C. If it’s still running after --timeout, the command force-stops it. Stopping a simulation that isn’t running succeeds.
Usage
The simulation ID or .sim.yaml path that you passed to postman simulation run.
Options
The number of seconds to wait for the simulation to shut down before force-stopping it. Defaults to 15.
Prints the result as machine-readable data: wasRunning, forced (whether the simulation had to be force-stopped), pid, and port. If the command fails, it prints nothing on stdout and writes { "error": "<message>", "code": <exit code> } to stderr.
Examples
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.
Prints the result as machine-readable data: simulationId, name, created, routing, mocks, and workspaceId. If the command fails, it prints nothing on stdout and writes { "error": "<message>", "code": <exit code> } to stderr.
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. The default is the simulation’s name followed by six hexadecimal characters, such as checkout-3f9c1a. A simulation with no name gets new-mock- and six hexadecimal characters instead. In an interactive terminal you’re asked to confirm or change the default, and outside one the default is used. Redeploying keeps the existing slug.
Lets anyone with the link reach the server. A new server is private by default, so callers must send a Postman API key in the x-api-key header.
Requires a Postman API key to reach the server. This is the default for a new server, and the option is kept for compatibility. You can’t pass both --public and --private.
Uses the defaults and skips all questions. A new server is private. Redeploying keeps the visibility the server already has.
Your Postman API key. Defaults to your postman login session.
Prints the live server’s details, such as the URL and visibility, as machine-readable data. This also skips the questions for the name, slug, and visibility, and takes each default.
Examples
postman simulation log
Use the postman simulation log command to browse a deployed simulation’s request and response history, with the newest entries first. Provide the mock server’s ID, which you can get from postman simulation deploy or postman simulation get.
By default, the command streams the entries interactively. Use the --json option for machine-readable output.
To use this command, sign in to Postman with the postman login command, or pass an --api-key.
Usage
The ID of the deployed simulation whose logs you want to view.
Options
Filters entries by the member mock that served them, using the member’s route key. Repeat the option to include several members. The postman simulation get command lists each member’s route key.
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. The default applies when you pass --json.
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.
Example
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 simulation removes the .sim.yaml and its <name>.context.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.
Prints the result as machine-readable data. Requires --yes, because a confirmation prompt would break the JSON output. If the command fails, it prints nothing on stdout and writes { "error": "<message>", "code": <exit code> } to stderr.