Postman CLI mock commands (postman mock)

A cloud mock’s ID, or a path to a local mock. The path can be a mock’s config.yaml file, a mock directory such as postman/mocks/<slug>, or a .js handler script.

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.

Loads one or more local .dataset.yaml files, or directories of them, so the mock’s request handlers can read them with pm.datasets(<id>). Pass --dataset more than once to load multiple datasets. The datasets load before the mock starts.

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.

The workspace that owns the run, used to record its start history. Auto-resolved when you run a cloud mock by its ID. Required to record the history of a run started from a local path.

Don’t record this run in the mock’s start history.

The live output format. Use auto to print human-readable request and response logs. Use ndjson to stream one JSON event per line on stdout instead, for machine-readable output. 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.

The path to the source collection or OpenAPI specification file. The source type is auto-detected. If omitted, the command generates a sample mock.

The output directory for the generated mock. You can’t use this option with --update.

A display name for the generated mock. With a source, this defaults to the collection’s or specification’s own name. Required when [source-path] is omitted, since the sample mock has no source name to default to. With --update, renames the mock.

The port the mock listens on. With --update, changes the mock’s port.

How the mock behaves:

• static — (Default) Replays the examples.
• stateful — Keeps records, with handlers for create, read, list, update, and delete operations.
• ai — Generates a stateful mock with realistic data and business rules, inferred from the specification, collection, or dataset you give it. Postman generates it, so you must sign in with the postman login command.

The same as --mode stateful. Generates handlers that store data with pm.state for endpoints that map to create, read, list, update, and delete operations, instead of returning static example responses. Other endpoints keep static responses. An endpoint whose resource has no create endpoint also keeps a static response. For a local file, the command generates the handlers on your machine. With --workspace, --spec, --collection, or --dataset, Postman generates them and validates them with seed data. You can’t combine --stateful with a --mode other than stateful.

Used with --mode ai, rules the source doesn’t state, such as "Orders can only be canceled before they ship". Without this option, the AI works from the source alone. Instructions can be up to 2,000 characters, and the command refuses longer text before it sends anything. The mock records the instructions, so --update reuses them.

Used with --mode ai, fails instead of falling back to a mock built without AI. If Postman would build the mock without AI, the command refuses it, exits with code 1, and writes or saves nothing. The error’s errorCode names the reason. If the AI’s rules reach only some operations, the command keeps the mock and exits with code 4. You can’t use this option with any other --mode.

Generates the mock from a specification in Postman, by ID, instead of a local file. With --workspace, the mock stays linked to the specification and regenerates when the specification changes.

Generates the mock from a collection in Postman, by ID, instead of a local file. With --workspace, the mock stays linked to the collection and regenerates when the collection changes.

Generates the mock from a dataset. Each table becomes a resource, and its first 20 rows become the records. Pass the ID of a dataset in Postman, or the path to a local .dataset.yaml file with CSV and JSON sources. Postman generates the mock in stateful mode by default, or in ai mode. In ai mode, the AI sees the column names and types, never the rows.

Overwrites the config.yaml or default.js file in the output directory if the directory already holds a mock. Other files are kept. A non-empty directory with no mock in it is never written to, with or without --force.

Updates an existing mock in place from the source. Provide the path to a local mock’s config.yaml file, or the directory that contains it. This regenerates the default scenario handler and preserves the existing scenarios. It also preserves the name and port, unless you pass --name or --port. If you omit the source and --mode, the command uses the source, mode, and instructions recorded by the mock. Any source or --mode you do pass replaces what the mock recorded, so a later update that omits them uses the new values. You can’t use this option with --output.

To update a cloud mock, provide its ID. Postman regenerates the mock in the mode it’s linked to, with its recorded instructions, unless you pass --mode or --instructions. You can’t pass two sources. An AI mock isn’t regenerated each time its source changes, so run this command to refresh it.

Creates the mock in the specified Postman workspace. You can’t use this option with --output, --force, or --update with a local mock path. With --deploy, it only selects the workspace to push to. With --update and a cloud mock ID, it names the workspace that holds the mock.

Uploads the generated mock 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. Uses the workspace from --workspace, or the workspace linked to this project.

Requires --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. The command refuses this option without --deploy. Defaults to the mock’s name followed by six hexadecimal characters, such as orders-3f9c1a.

Used with --deploy, prints the live server’s details as machine-readable data instead of a summary.

How long to wait for Postman to generate the mock, in milliseconds.

Your Postman API key, used for anything Postman generates, saves, or deploys. 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. When Postman names the error, the output also includes errorCode, and hint when Postman suggests a fix. When Postman builds an AI mock without AI, ai includes fallbackReason and, if there is one, hint. When AI’s rules reach only some operations, aiCoverage lists them and the operations it dropped, and partial is true.

Always exits with code 0, even on failure.

A cloud mock’s ID, or the path to a mock (or a directory that contains one).

Prints the mock 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.

Your Postman API key, used to authenticate when you get a cloud mock by its ID. Defaults to your postman login session.

A directory to search for local mocks. Defaults to postman/mocks. You can’t combine it with --workspace.

Lists the mocks in the specified Postman Cloud workspace instead of local mocks. Listing is local-first, so this option is only needed to list cloud mocks. 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.

Prints the mock 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.

A cloud mock’s ID, or the path to a mock (or a directory that contains one).

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.

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.

The cloud mock ID or path that you passed to postman mock run. A path can be a mock directory, a config.yaml or .yaml manifest, or a .js handler.

The number of seconds to wait for the mock to shut down before force-stopping it. Defaults to 15.

Prints the result as machine-readable data: wasRunning, forced (whether the mock 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.

The path to the mock in your repository, for example ./postman/mocks/orders.

The Postman workspace to upload the mock to, by ID. Defaults to the workspace already linked to your project.

Your Postman API key. If omitted, the command uses your postman login session.

Prints the result as machine-readable data: mockId, name, created, deployed, workspaceId, and postmanUrl. If the command fails, it prints nothing on stdout and writes { "error": "<message>", "code": <exit code> } to stderr.

The ID of the cloud mock to deploy.

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. Defaults to the mock’s name followed by six hexadecimal characters, such as orders-3f9c1a. A mock with no name gets new-mock- and six hexadecimal characters instead. Redeploying keeps the existing slug.

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.

The ID of the deployed mock server whose logs you want to view.

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.