Collection commands

This topic covers collection-related commands for the Postman CLI.

You can run your collections with HTTP requests using the postman collection run command. With a paid plan, you can also run collections with gRPC and GraphQL requests.

Use the postman collection migrate command to migrate collections from the v2.1 JSON format to the v3 YAML format. You can also use the postman collection lint command to check that your collection matches the v3 format schema.

`postman collection run`

This command runs a collection and displays run results in the terminal. If you’re signed in to Postman, the command sends the run results to the Postman cloud. Learn how to sign in to Postman with the postman login command.

Specify the collection with its file path if you’re running it locally. If you’re signed in to Postman, specify the collection with its ID to send the results to the Postman cloud.

You can find the collection ID in Postman. Click the Items tab, click Collections in the sidebar, and select a collection. Then click the Info tab in the right sidebar to view or copy the collection ID.

When you run a collection, the Postman CLI runs its requests in order, and one pass through the requests is an iteration. To run the same requests against multiple sets of data, provide iteration data with --iteration-data, or with --iteration-data-dataset and --iteration-data-view. The CLI runs one iteration per row of data, and each row’s columns are available to your requests and scripts as variables, such as {{name}}.

Usage

$ postman collection run <collection> [options]

One of the following:

A collection file path if running locally.
A collection ID (UUID format) if signed in to Postman.

Options

--bail [optional modifiers]

Specifies whether to stop a collection run on encountering the first error. --bail can optionally accept two modifiers: --folder and --failure. --folder skips the entire collection run if there are any errors. If a test fails, --failure stops the collection run after completing the current script.

--cookie-jar [path]

Specifies the file path for a JSON cookie jar. This uses the tough-cookie library to deserialize the file.

--delay-request [number]

Defaults to 0

Specifies a delay (in milliseconds) between requests.

--disable-unicode

Replaces all symbols in the output with their plain text equivalents.

--environment [UID] or [file-path], -e

Specifies an environment file path or UID.

--env-var [environment-variable-name]=[environment-variable-value]

Specifies environment variables in a key=value format. Multiple CLI environment variables can be added by using --env-var multiple times, for example: --env-var "this=that" --env-var "alpha=beta".

--export-cookie-jar [path]

Specifies the path where the Postman CLI will output the final cookie jar file after completing a run. This uses the tough-cookie library to serialize the file.

--global-var [global-variable-name]=[global-variable-value]

Specifies global variables in a key=value format. Multiple CLI global variables can be added by using --global-var multiple times, for example: --global-var "this=that" --global-var "alpha=beta".

--globals [file-path], -g

Specifies a path to a file containing global variables. Global variables are similar to environment variables but have lower precedence and can be overridden by environment variables having the same name.

--integration-id [ID]

(This option is only supported in Postman v11 and earlier.) Specifies an integration ID when using an integration with CI/CD. This sends the Postman CLI results to the correct integration in Postman.

--iteration-count [number], -n

Specifies the number of times the collection will run when used in conjunction with the iteration data file.

--iteration-data [file-path], -d

Specifies the local file path to a data file (JSON or CSV) to use for each iteration.

You can’t use --iteration-data together with --iteration-data-dataset.

--iteration-data-dataset [dataset-path-or-id]

Specifies the dataset whose view provides the rows used for each iteration. Unlike --iteration-data, which reads a static JSON or CSV file, this option draws the iteration rows from a dataset view, so the data can come from a database and be shaped with SQL. Use one of the following:

The path to a local dataset file (.dataset.yaml) when running a collection locally.
A cloud dataset ID when running a collection by its ID.

This option requires --iteration-data-view. You can’t use --iteration-data-dataset together with --iteration-data.

--iteration-data-view [view-name-or-id]

Specifies the name or unique identifier of the view to run from the dataset provided by --iteration-data-dataset. The view returns rows that are used for each iteration. This option requires --iteration-data-dataset.

--dataset [dataset-path-directory-or-id]

Makes one or more datasets available to collection scripts through pm.datasets. You can provide multiple datasets by specifying --dataset multiple times. Do one of the following:

When running a collection locally, specify the path to a dataset file (.dataset.yaml) or a directory that contains datasets.
When running a collection by its ID, specify a cloud dataset ID. Scripts can then query cloud datasets through pm.datasets(<id>), resolved from your postman login session. You must pass --dataset to make pm.datasets available in a collection run by ID.

When you use this option, automatic dataset discovery from the collection’s parent repository is turned off.

For a collection run by ID, this option doesn’t scope dataset access. A script can call pm.datasets(<id>) for any dataset your postman login session can read, including datasets you didn’t pass to --dataset. Only run collections you trust against a signed-in session.

-i [requestUID] or [folderUID]

Runs only the specified folder UID or request UID from the collection. Multiple items can be run in order by specifying -i multiple times, for example: postman collection run collectionUID -i folder1UID -i folder2UID.

-i [requestName] or [folderName] or [folderPath]

Runs only the specified folder name or request name from the collection. This option also accepts a folder path relative from the root of the collection. For example, postman collection run <rootFolder>/<folderName>/<requestName>.

If there are duplicate names, the Postman CLI runs the folder or request that appears first.

--ignore-redirects

Prevents the Postman CLI from automatically following 3XX redirect responses.

--insecure, -k

Turns off SSL verification checks and enables self-signed SSL certificates.

--mock [file-path]

Specifies the path to a mock configuration file in JSON format. This starts a mock using the specified configuration, runs the collection against the mock, and then stops it. The option isn’t supported for mocks in the Postman cloud.

--no-insecure-file-read

Prevents reading of files situated outside of the working directory.

--output <folder>

Specifies the directory where Postman streams raw run data to YAML files on disk as each request finishes.

The following files are created in the specified directory:

<prefix>.collection-run-summary.yaml — A run summary that’s created when the run starts and updated throughout the run until it completes, is stopped, or fails.
<prefix>.collection-run-executions.yaml — A multi-document YAML file that streams each completed request to disk as it completes, rather than writing the file all at once at the end of the run.

By default, the filename prefix is generated as <collection-slug>-<timestamp>. This enables multiple runs to write to the same output folder without overwriting one another. If you specify a custom prefix, Postman automatically removes characters that aren’t valid in Windows filenames.

This option is in beta for Postman Enterprise plans only and can’t be used with the --reporters option. To use this option, sign in to Postman with the postman login command.

--postman-api-key [api-key]

Specifies the API key used to load resources from the Postman API. Only supported in the US region. To authenticate in the EU region, use postman login --region.

--reporters [reporter], -r [reporter]

Generates a local report for the collection run in the specified format: cli, json, junit, and html. If the --reporters option isn’t specified, the cli report is output by default. Only the cli report output is supported for HTTP, gRPC, and GraphQL collections in v3 format (YAML).

To learn more, go to Generate collection run reports using the Postman CLI.

--silent

Turns off terminal output.

--simulate [file-path]

Specifies the path to a simulation configuration file in YAML format. This runs the collection with a simulation applied to mocks. To create a simulation and apply it to a mock, see Create and run simulations in Postman.

This option is available on Postman paid plans. The option isn’t supported for mocks in the Postman cloud.

--ssl-client-cert-list <path>

Specifies the path to a client certificates configuration (JSON).

--ssl-client-cert <path>

Specifies the path to a client certificate (PEM).

--ssl-client-key <path>

Specifies the path to a client certificate private key.

--ssl-client-passphrase <passphrase>

Specifies the client certificate passphrase (for a protected key).

--ssl-extra-ca-certs <path>

Specifies more trusted CA certificates (PEM).

--suppress-exit-code, -x

Specifies whether to override the default exit code for the current run.

--timeout [number]

Specifies the time (in milliseconds) to wait for the entire collection run to complete.

--timeout-request [number]

Defaults to 0

Specifies a time (in milliseconds) to wait for requests to return a response.

--timeout-script [number]

Defaults to 0

Specifies the time (in milliseconds) to wait for scripts to complete.

--verbose

Shows detailed information for the collection run and each request sent.

--working-dir [path]

Sets the path of the working directory to use while reading files with relative paths. This defaults to the current directory.

--report-events

Uploads run results to Postman, including per-test assertion names, pass or fail status, and error details. The CLI prints a View on Postman link when the upload succeeds. Click the link to access the Run results page for the specific collection run. You can share this page’s URL with your team, and teammates can open it to view the report. You can also view the results in the API Catalog. Click Integrated services, click your service, and open the Test tab.

Cloud-backed collections (run by ID) upload run results whenever you use this option, including from local runs. V2 and V3 HTTP-only Git-native collections (run by path) upload run results from CI environments only. Local runs proceed without reporting. In verbose mode, the CLI notes that results are only uploaded from CI.

Reporting is supported for HTTP collections. Collections that use other protocols, such as gRPC, WebSocket, MQTT, or Socket.IO, or scripts or authentication that Postman can’t include in the report, run normally but aren’t reported. In these cases, the CLI prints a message explaining that the run results won’t be uploaded.

Examples

$ postman collection run postman/collections/myCollectionName
$ 
$ postman collection run 12345678-12345ab-1234-1ab2-1ab2-ab1234112a12

To drive iterations from a dataset view, pass --iteration-data-dataset and --iteration-data-view together. Use a local dataset file with a local collection, or a cloud dataset ID with a collection run by its ID:

$ postman collection run postman/collections/myCollectionName \
>   --iteration-data-dataset ./postman/datasets/customers.dataset.yaml \
>   --iteration-data-view active-customers
$ 
$ postman collection run 12345678-12345ab-1234-1ab2-1ab2-ab1234112a12 \
>   --iteration-data-dataset 14e30f6c-1234-1234-1234-cafef00dc0de \
>   --iteration-data-view active-customers

Learn more at Run a collection using the Postman CLI and Use the Postman CLI with GitHub Actions.

`postman collection migrate`

Use the postman collection migrate command to migrate your existing v2.1 collection to the new v3 collection format. A new folder containing a YAML file for each request is created and can be run with the postman collection run command.

Usage

$ postman collection migrate <collection-file> [options]

<collection-file>

Path to the existing v2.1 collection file to migrate.

Options

-o, --output <directory>

Specifies the directory to migrate your new collection to. If you don’t specify a directory, the Postman CLI saves the new collection in the current directory.

Examples

$ postman collection migrate your-existing-collection.json
$ 
$ postman collection migrate your-existing-collection.json --output path/to/your-new-collection

`postman collection lint`

Use the postman collection lint command to verify that the collection matches the v3 format schema.

Usage

$ postman collection lint <collection> [options]

Path to a v3 collection file or directory to lint.

Options

-f, --fail-severity <value>

Defaults to error

Exit with a failure code if diagnostics at this severity level or higher are present. Accepted values are error and warning.

With error, the command fails only when errors are present. With warning, the command fails when warnings or errors are present.

-r, --reporter <value>

Defaults to cli

Specifies the output format. Accepted values are cli and json.

Examples

$ postman collection lint ./postman/collections
$ 
$ postman collection lint ./postman/collections --fail-severity warning
$ 
$ postman collection lint ./postman/collections/collectionName/requestName.request.yaml --reporter json