Run a monitor using the Postman CLI

Monitors enable you to regularly check the health and performance of your APIs. You can use the Postman CLI to trigger monitor runs within your CI/CD pipeline. Then your team can use your Postman tests to automatically catch regressions and configuration issues during your deployment process. Depending on whether the monitor run passes or fails, you can push or roll back your changes.

By default, Postman supports monitoring public APIs. If you’re on a paid plan, you can use Private API Monitoring to monitor your organization’s internal APIs from your internal network using runners, without publicly exposing your endpoints. As a Team Admin or Super Admin, you can create runners when you configure a monitor and then set up the runner in your internal network using the postman runner start command.

Once your monitor is created, add the Postman CLI installation command and postman monitor run command into your CI/CD script to integrate them into your workflow. Postman recommends replacing your monitor ID and API key with variables.

The Postman CLI triggers the monitor using the postman monitor run command and polls Postman for the run’s completion. Then the Postman CLI makes the test results available in the monitor results in Postman. When the Postman CLI triggers a monitor for a public API, the collection and its tests run in the Postman cloud. When the Postman CLI triggers a monitor for an internal API, the collection and its tests run in your internal network.

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

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.

Configure a monitor for your CI/CD pipeline

To configure a monitor for your CI/CD pipeline, do the following:

1. Click Monitors in the sidebar, then create or edit a monitor.
2. Under Run, select Postman CLI to only run the monitor when triggered by the Postman CLI.
3. With paid plans, you can monitor internal APIs using runners. Under Runners, select Manually Select, then select one of your team’s runners from the list. If there are no runners in the list, contact your Team Admin to create and set up a runner in your team.
4. Continue configuring your monitor, and click Create Monitor.

Run a monitor within your CI/CD pipeline

1. Click Monitors in the sidebar, then select the monitor you configured earlier.

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 Actions:

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 ${{ vars.MONITOR_ID }}

You can use the Postman CLI to run a monitor linked to a collection that imports packages from your team’s Postman 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.