Run a collection using the Postman CLI

You can use the Postman CLI to manually run collections to test the functionality of your API. You can also use the Postman CLI to automate collection runs in CI/CD pipelines.

Postman supports running HTTP collections. You can't run multi-protocol collections.

When the Postman CLI runs a collection, the collection and its tests run locally, and the results are sent to the Postman cloud using an API call.

The Postman CLI doesn't support OAuth 2.0 authentication grant types that require user interaction, such as authorization code, to manually generate an access token. To learn more, see OAuth 2.0 overview.

Run a collection locally with the Postman CLI

You can use the Postman CLI to run the requests in a collection or a folder.

1. Download and install the Postman CLI.

2. Select Collections in the sidebar and select the collection or folder you want to run.

   You can also run a collection or folder that's linked to an API. Learn more about adding a collection to an API in the Postman API Builder.

3. Select Run.

   

4. On the Functional tab, select Automate runs via CLI.

   

   If you're running a collection linked to an API that's connected to a Git repository, replace the collection ID with the path to the collection file in your remote repository.

5. Under Run on Postman CLI, select Add API Key. Do one of the following:

   • Select Generate Key to create a new API key. Enter a name for the API key and select Generate. Select Copy to copy the key and save it somewhere safe.
   • Select Use Existing Key and enter a valid API key.

6. Select Insert Key.

7. Select Copy to copy the commands.

8. Paste and run the commands in your terminal. After running the commands, the Postman CLI outputs a run report and a link to the run results in Postman.

   In the run report, test-scripts refers to post-response scripts.

9. Follow the link to check the results in Postman.

   

Run a collection in CI/CD

When the collection runs to your satisfaction, you can copy the commands into your CI/CD script to integrate them into your workflows. When adding the commands to your CI/CD script, you may want to replace the API key with a variable.

To run a collection in CI/CD, do the following:

1. Select Collections in the sidebar and select the collection or folder you want to run.

   You can also run a collection or folder that's linked to an API. Learn more about adding a collection to an API in the Postman API Builder.

2. Select Run.

   

3. On the Functional tab, select Automate runs via CLI.

   

4. Under Run on CI/CD, select Configure command.

5. Select a Collection to run during pipeline builds. You can also select an Environment to use.

   If needed, select Add Another Collection to select more collections to run.

6. Select the CI/CD Provider and Operating system for your CI/CD pipeline.

7. Select Copy to copy the Postman CLI configuration. You can also select Copy Postman CLI Command.

   

8. Add the Postman CLI configuration to your CI/CD script. This process depends on your CI tool.

Run a collection in a specific order

By default, when you generate the command to run a collection from the Collection Runner, a single Collection ID for the collection is specified. This runs the folders and requests in that collection in the sequence they're listed in the collection.

If you need to change the request order, select a request in the Collection Runner and drag it to its new location in the order. You can also remove an individual request from the run by clearing the checkbox next to its name.

When you change the folder and request sequence, the generated command also changes. In addition to the Collection ID, the generated command specifies a number of folder and request UIDs with the -i option. This runs each of the folders or requests in that specified order.

Run a collection that uses test data files

The Postman CLI can't run requests that use files in your local working directory to send body data. If your collection has requests that use files, upload your test data files to make them available to the Postman CLI.

Run a collection that uses packages

Running packages from the Postman CLI is available with Postman Professional and Enterprise plans.

You can add scripts and tests to packages in your team's Package Library, and run the contents of packages from the Postman CLI. Learn how to add packages to the Package Library, and import packages into your scripts.