> This page is for Postman Docs, version Latest (v12) (default).
> For other versions, use one of these documentation indexes:
> - Latest (v12) (default): https://learning.postman.com/latest-v-12/llms.txt
> - v11: https://learning.postman.com/v11/llms.txt

> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://learning.postman.com/llms.txt.

# Run a monitor using the Postman CLI

> Trigger a Postman monitor run in your CI/CD pipeline with the Postman CLI to catch regressions before you deploy.

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.

Monitors run HTTP, GraphQL, and gRPC requests.

> **Info**
>
> Support for running GraphQL and gRPC requests in monitors is in beta for Enterprise plans only. To learn more, see [Supported request types](/docs/monitoring-your-api/setting-up-monitor/#supported-request-types).

By default, Postman supports monitoring public APIs. If you're on an Enterprise 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-monitoring/#postman-runner-start).

Once your monitor is created, add the Postman CLI installation command and [`postman monitor run` command](/docs/postman-cli/postman-cli-monitoring/#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](/docs/postman-cli/postman-cli-monitoring/#postman-monitor-run) 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**
>
> To use the `postman runner start` and `postman monitor run` commands, sign in to Postman with [the `postman login` command](/docs/postman-cli/postman-cli-auth/#postman-login).

> **Info**
>
> 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/use/send-requests/authorization/oauth-20/#oauth-20-overview).

## Configure a monitor for your CI/CD pipeline

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

1. Click the ![Services icon](https://assets.postman.com/postman-docs/aether-icons/v12/descriptive-services-stroke.svg#icon) **Services** tab in the sidebar.
2. Click **Monitors**, then [create or edit a monitor](/docs/monitoring-your-api/setting-up-monitor/).
3. Under **Run**, select **Postman CLI** to only run the monitor when triggered by the Postman CLI.
4. With an Enterprise plan, you can monitor internal APIs using runners. Under **Runners**, click the dropdown list, 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.
5. Continue configuring your monitor, and click **Create Monitor**.

> **Info**
>
> A monitor triggered by the Postman CLI runs in the Postman Cloud or, with Private API Monitoring, your internal network. For sensitive values, use a [Shared Vault](/docs/use/postman-vault/postman-vault-key/#postman-shared-vault) secret and [share the variable](/docs/use/send-requests/variables/share-variables/#share-a-secure-variable-value). Local Vault secrets aren't available to the run.

## Run a monitor within your CI/CD pipeline

1. Click the ![Services icon](https://assets.postman.com/postman-docs/aether-icons/v12/descriptive-services-stroke.svg#icon) **Services** tab in the sidebar.

2. Click **Monitors**, then select the [monitor you configured earlier](#configure-a-monitor-for-your-cicd-pipeline).

3. Select ![Options icon](https://assets.postman.com/postman-docs/aether-icons/v12/icon-action-options-stroke.svg#icon) **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 icon](https://assets.postman.com/postman-docs/aether-icons/v12/icon-action-copy-stroke.svg#icon) **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 icon](https://assets.postman.com/postman-docs/aether-icons/v12/icon-action-copy-stroke.svg#icon) **Copy to clipboard** to copy the commands.

7. Paste the Postman CLI installation, [`login`](/docs/postman-cli/postman-cli-auth/#postman-login), and [`monitor`](/docs/postman-cli/postman-cli-monitoring/#postman-monitor-run) 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**
>
> 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.