# 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](/docs/postman-cli/postman-cli-overview/) to trigger [monitor runs](/docs/monitoring-your-api/intro-monitors/) 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](/docs/monitoring-your-api/runners/overview/) to monitor your organization's internal APIs from your internal network using runners, without publicly exposing your endpoints. As an [Admin or Super Admin](/docs/administration/roles-and-permissions/#team-roles), 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](/docs/postman-cli/postman-cli-options/#postman-runner-start).

Once your monitor is created, add the Postman CLI installation command and [`postman monitor run` command](/docs/postman-cli/postman-cli-options/#postman-monitor-run) 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](/docs/monitoring-your-api/viewing-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.

<Info class="iconless-callout">
  Postman Monitors support HTTP collections. You can't use monitors with multi-protocol collections.
</Info>

<Info class="iconless-callout">
  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](/docs/sending-requests/authorization/oauth-20/#oauth-20-overview).
</Info>

## Configure a monitor for your CI/CD pipeline

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

1. Click <img alt="Monitor icon" src="https://assets.postman.com/postman-docs/aether-icons/entity-monitor-stroke.svg#icon" width="16px" /> **Monitors** in the sidebar, then [create or edit a monitor](/docs/monitoring-your-api/setting-up-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 Admin to [create and set up a runner](/docs/monitoring-your-api/runners/configure-a-runner/) in your team.
4. Continue configuring your monitor, and click **Create Monitor**.

## Run a monitor within your CI/CD pipeline

1. Click <img alt="Monitor icon" src="https://assets.postman.com/postman-docs/aether-icons/entity-monitor-stroke.svg#icon" width="16px" /> **Monitors** in the sidebar, then select the [monitor you configured earlier](#configure-a-monitor-for-your-cicd-pipeline).

2. Select <img alt="Options icon" src="https://assets.postman.com/postman-docs/aether-icons/action-options-stroke.svg#icon" width="16px" /> **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 <img alt="Copy icon" src="https://assets.postman.com/postman-docs/aether-icons/action-copy-stroke.svg#icon" width="16px" /> **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 <img alt="Copy icon" src="https://assets.postman.com/postman-docs/aether-icons/action-copy-stroke.svg#icon" width="16px" /> **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 use the [Postman CLI GitHub Action](/docs/postman-cli/postman-cli-github-actions/) to run a monitor:

```yaml
name: API Testing

on: push

jobs:
  monitor:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Run monitor
        uses: postmanlabs/postman-cli-action@v1
        with:
          command: 'monitor run ${{ vars.MONITOR_ID }}'
          api-key: ${{ secrets.POSTMAN_API_KEY }}
```

<Info class="iconless-callout">
  You can use the Postman CLI to run a monitor linked to a collection that imports packages from your team's [Postman Package Library](/docs/tests-and-scripts/write-scripts/packages/package-library/). Learn how to [add packages](/docs/tests-and-scripts/write-scripts/packages/package-library/#add-a-package) to the package library, and [import packages](/docs/tests-and-scripts/write-scripts/packages/package-library/#import-a-package) into your scripts.

  You can also use the Postman CLI to run a monitor linked to a collection that [imports external packages](/docs/tests-and-scripts/write-scripts/packages/external-package-registries/) from npm or JSR package registries.
</Info>