> ## Documentation Index
> Fetch the complete documentation index at: https://pulse-41cf5b0d.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage and Configure PulseGuard Monitors via pulse

> List, inspect, create, and update monitors with the pulse CLI. Use pulseguard.yaml for Monitoring as Code and sync your setup with your code.

The `pulse monitors` command group is the heart of the CLI. You can inspect every monitor in your account, drill into the details of a single check, and — most powerfully — declare your entire monitoring setup in a `pulseguard.yaml` file and apply it with a single command. Treating monitor configuration as code means your monitoring setup is version-controlled, reviewable, and reproducible.

## Listing monitors

Get a quick overview of all monitors in your account:

```bash theme={null}
pulse monitors list
```

The output is a formatted table with the following columns:

| Column     | Description                                              |
| ---------- | -------------------------------------------------------- |
| STATUS     | Current status: `UP`, `DOWN`, `PAUSED`, or `MAINTENANCE` |
| NAME       | The monitor's display name                               |
| TYPE       | Monitor type: `HTTP`, `SSL`, `BROWSER`, etc.             |
| URL        | The target URL (truncated at 40 characters)              |
| INTERVAL   | How often the monitor checks, in seconds                 |
| LAST CHECK | Time of the most recent check result                     |

The `ls` alias is also available:

```bash theme={null}
pulse monitors ls
```

For scripting and automation, request machine-readable output with the `--json` flag:

```bash theme={null}
pulse monitors list --json
```

This outputs a JSON array of all monitor objects, suitable for piping into `jq` or other tools.

## Getting monitor details

Inspect a single monitor by its ID to see its full configuration and recent check events:

```bash theme={null}
pulse monitors get <id>
```

For example:

```bash theme={null}
pulse monitors get mon_abc123
```

The output shows the monitor's name, current status, URL, type, interval, timeout, last check timestamp, and a list of recent events with timestamps, statuses, latencies, and any error reasons.

Use `--json` to get the full monitor object as JSON:

```bash theme={null}
pulse monitors get mon_abc123 --json
```

<Tip>
  Find a monitor's ID from the `pulse monitors list` output, or from the monitor's URL in the PulseGuard dashboard: `/dashboard/monitors/<id>`.
</Tip>

## Monitoring as Code with YAML

The most powerful feature of the CLI is the ability to define your monitors declaratively in a YAML file and apply them idempotently. Monitors are matched by name: if a monitor with the same name already exists it is updated, otherwise it is created.

### Create a pulseguard.yaml file

Add a `pulseguard.yaml` file to the root of your repository:

```yaml pulseguard.yaml theme={null}
monitors:
  - name: Production API
    url: https://api.example.com/health
    type: HTTP
    interval: 60
    timeout: 10
    method: GET
    alertThreshold: 2
    checkRegions:
      - us-east-1
      - eu-west-1

  - name: SSL Certificate
    url: https://example.com
    type: SSL
    interval: 3600

  - name: Login Flow
    url: https://example.com/login
    type: BROWSER
    interval: 300
```

Each entry in the `monitors` array supports the following fields:

| Field            | Required | Description                                      |
| ---------------- | -------- | ------------------------------------------------ |
| `name`           | ✅        | Unique display name; used as the idempotency key |
| `url`            | ✅        | The URL to monitor                               |
| `type`           | ✅        | `HTTP`, `SSL`, or `BROWSER`                      |
| `interval`       | ✅        | Check frequency in seconds                       |
| `timeout`        |          | Request timeout in seconds (HTTP monitors)       |
| `method`         |          | HTTP method, defaults to `GET`                   |
| `alertThreshold` |          | Number of consecutive failures before alerting   |
| `checkRegions`   |          | List of regions from which to run checks         |

### Apply the configuration

Run the following command from the directory containing your `pulseguard.yaml`:

```bash theme={null}
pulse monitors apply -f pulseguard.yaml
```

The CLI fetches your existing monitors, compares them against the YAML, and creates or updates each entry. At the end it prints a summary:

```
✔ Applied: 2 created, 1 updated
```

### Preview changes before applying

Use `--dry-run` to see exactly what `apply` would do without making any changes:

```bash theme={null}
pulse monitors apply -f pulseguard.yaml --dry-run
```

```
DRY RUN — no changes will be made

  [+] Production API
  [~] SSL Certificate
  [+] Login Flow
```

`[+]` means the monitor would be created; `[~]` means it would be updated.

<Note>
  `pulse monitors apply` is safe to run repeatedly. Monitors that already match their YAML definition are not modified unnecessarily. This makes it suitable for use in a deployment pipeline.
</Note>

### Export existing monitors to YAML

If you have monitors you created in the dashboard and want to bring them under version control, export them all to a YAML file:

```bash theme={null}
pulse monitors import
```

This writes a `pulseguard.yaml` file in the current directory. To specify a different output path:

```bash theme={null}
pulse monitors import -o infrastructure/monitors.yaml
```

The exported file is a valid input for `pulse monitors apply`, so you can use it immediately as your Monitoring as Code baseline.

## Triggering an immediate check

Force a monitor to run a health check right now without waiting for its next scheduled interval:

```bash theme={null}
pulse trigger <id>
```

You can optionally override the target URL for a one-off test:

```bash theme={null}
pulse trigger mon_abc123 --url https://staging.example.com/health
```

The CLI displays the result — status, latency, HTTP status code, and any error — and exits with code `1` if the check returns `DOWN`, making it easy to use in scripts.

<Note>
  Instant trigger is supported only for `HTTP` monitors. Attempting to trigger an `SSL` or `BROWSER` monitor returns a `422` error.
</Note>

## Tailing live logs

Stream check events from a monitor in real time, similar to `tail -f` on a log file:

```bash theme={null}
pulse logs tail <id>
```

The CLI first shows the last 20 events, then polls for new ones every 5 seconds, printing each new event as it arrives. Press `Ctrl+C` to stop.

Control how many past lines are shown on startup with `-n`:

```bash theme={null}
pulse logs tail mon_abc123 -n 50
```

Adjust the poll interval in milliseconds with `--interval` (minimum 2000 ms):

```bash theme={null}
pulse logs tail mon_abc123 --interval 3000
```

Each log line shows the timestamp, a coloured status indicator, latency, check region, and any error reason:

```
  10:42:01  ● UP         123ms  [us-east-1]
  10:42:06  ● UP         118ms  [eu-west-1]
  10:42:11  ● DOWN         ---  [us-east-1] connection refused
```