Run a monitor using the Postman CLI

You can use the Postman CLI to run monitors to test the functionality of your API. You can also use the Postman CLI to automate monitors in your CI/CD pipelines. To learn more about monitors, see Monitor health and performance of your APIs in Postman.

Postman Monitors support HTTP collections. You can't use monitors with multi-protocol collections.

When the Postman CLI runs a monitor, the collection and its tests run on the Postman cloud. The Postman CLI invokes the monitor and polls Postman for the run's completion.

The Postman CLI doesn't support OAuth 2.0 authentication. To learn how to use an OAuth 2.0 token with the Postman CLI, see OAuth 2.0 overview.

Run a monitor locally with the Postman CLI

1. Install the Postman CLI.

2. Click Monitors in the sidebar and select the monitor you want to run.

3. Select View more actions > Run using Postman CLI in the upper right of the workbench.

4. Under Trigger Monitor Run, click Add API key. Do one of the following:

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

5. Click Insert Key.

6. Click Copy to clipboard to copy the monitor command.

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

Run a monitor in CI/CD

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, Postman recommends replacing your monitor ID and API key with a variable.

You can configure the monitor to only run when triggered by the Postman CLI.

To run a monitor in your CI/CD pipeline, do the following:

1. Click Monitors in the sidebar and select the monitor you want to run.

2. Select View more actions > Run using Postman CLI in the upper right of the workbench.

3. Under Trigger Monitor Run, click Add API key. Do one of the following:

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

4. Click Insert Key.

5. Click Copy to clipboard to copy the commands.

6. Paste the Postman CLI installation, login, and monitor commands into your CI/CD script. This process depends on your CI tool.

The following example shows how to add the Postman CLI commands to GitHub Action:

name: Automate monitors using Postman CLI

on: push

jobs:
  automated-api-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Postman CLI
        run: |
          curl -o- "https://dl-cli.pstmn.io/install/linux64.sh" | sh
      - name: Login to Postman CLI
        run: postman login --with-api-key ${{ secrets.POSTMAN_API_KEY }}
      - name: Run monitor
        run: |
          postman monitor run ${{ secrets.MONITOR_ID }}

Run a monitor that uses packages

You can use the Postman CLI to run a monitor linked to a collection that imports packages from your team's Package Library. Learn how to add packages to the Package Library, and import packages into your scripts.

You can also use the Postman CLI to run a monitor linked to a collection that imports external packages from npm or JSR package registries.