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 on CI/CD pipelines.

When the Postman CLI runs a collection, the collection and its tests run locally, and the results are sent to Postman servers as 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.

Running 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.

3. On the Overview tab, select Run.

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

   

5. In the Postman CLI command window, select Add API Key.

6. Select Generate Key (or Use Existing Key to enter an existing API key and skip to step #9).

7. Enter a name for the API key.

8. Select Generate.

9. Copy and save the API key.

10. Select Insert Key.

11. Select Copy.

12. Paste and run the commands in your terminal.

13. After running the commands, the Postman CLI generates a link. Follow the link to check the results on Postman.

    In your terminal, test-scripts refers to post-response scripts.

14. The collection run results display in the browser.

    

Running a collection in CI/CD

When the collection runs to your satisfaction, you can copy the commands into your CI/CD scripts to integrate them into your workflows. When adding the command 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.

2. On the Overview tab, 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 other collections to run.

6. Select the CI/CD Provider for your CI/CD pipeline.

7. Select the Operating system for your CI/CD pipeline.

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

   

9. Add the Postman CLI configuration to your CI/CD pipeline. The process for doing this depends on your CI tool.

Running 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 will run the folders and requests in that collection in the sequence they're listed in the collection.

If you need to change the order of execution, select a request in the Collection Runner and drag it to move it to its new 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 and Automate runs via CLI is selected, the command in the Postman CLI command window will also change. In addition to the Collection ID, the generated command will specify a number of folder and request UIDs with the -i option. This will run each of the folders or requests in that specified order.

Running 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.

Running a collection that uses packages

Executing packages from the Postman CLI is available on 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 pre-request and post-response scripts.