npm package: @redredchen01/monitoring-tools
Description: Network monitoring and health check CLI — ping, healthcheck, port-scan, uptime, alert, dashboard, watch
Author: redredchen01
Latest version: 1.0.0

# @redredchen01/monitoring-tools

> Network monitoring and health check CLI — ping, healthcheck, port-scan, uptime, alert, dashboard, watch

[![npm version](https://img.shields.io/npm/v/@redredchen01/monitoring-tools.svg)](https://www.npmjs.com/package/@redredchen01/monitoring-tools)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Install

```bash
npm install -g @redredchen01/monitoring-tools
```

## Quick Start

```bash
monitoring-tools ping --host google.com
monitoring-tools healthcheck --url https://example.com
monitoring-tools port-scan --host 192.168.1.1 --ports 22,80,443
monitoring-tools uptime --url https://example.com --count 5
monitoring-tools dashboard --config ./monitoring.json
```

## Commands

### `ping` — Measure latency

ICMP ping to a host or HTTP ping to a URL. Reports avg/min/max latency and packet loss.

```bash
monitoring-tools ping --host 8.8.8.8 --count 10
monitoring-tools ping --url https://example.com --count 5 --json
```

Options: `--host HOST`, `--url URL`, `--count N`, `--timeout SECS`, `--json`

---

### `healthcheck` — HTTP health check

Validate HTTP status code and response time. Exits 0 on pass, 1 on fail.

```bash
monitoring-tools healthcheck --url https://api.example.com/health
monitoring-tools healthcheck --url https://example.com --expected-status 200 --max-time 2
```

Options: `--url URL`, `--expected-status CODE`, `--max-time SECS`, `--method METHOD`, `--json`

---

### `port-scan` — Scan open ports

Scan a host's ports using bash `/dev/tcp` or `nc`. Reports open ports with service names.

```bash
monitoring-tools port-scan --host example.com
monitoring-tools port-scan --host 192.168.1.1 --ports 1-1024 --timeout 1
```

Options: `--host HOST`, `--ports RANGE`, `--timeout SECS`, `--json`

---

### `uptime` — Availability monitoring

Run repeated HTTP checks and report uptime percentage. Single-run (not a daemon).

```bash
monitoring-tools uptime --url https://example.com --count 20 --interval 10
```

Options: `--url URL`, `--count N`, `--interval SECS`, `--json`

---

### `alert` — Threshold alerting

Compare a numeric value against a threshold. Reads from `--value` or stdin.
Exits 0 if OK, exits 1 if threshold exceeded.

```bash
monitoring-tools alert --value 95 --threshold 90 --above
echo "3" | monitoring-tools alert --threshold 5 --below --message "Too few workers"
```

Options: `--value N`, `--threshold N`, `--above`, `--below`, `--message MSG`, `--json`

---

### `dashboard` — Multi-URL summary

Check multiple URLs from a JSON config or stdin and display a summary table.

```bash
monitoring-tools dashboard --config ./monitoring.json
echo '[{"url":"https://example.com","name":"Main"}]' | monitoring-tools dashboard
```

Config format: JSON array with `url` (required) and `name` (optional) per entry.

Options: `--config FILE`, `--timeout SECS`, `--json`

---

### `watch` — Periodic command runner

Re-run any shell command at an interval, displaying output with timestamps.

```bash
monitoring-tools watch --interval 5 --count 12 -- curl -s https://example.com/status
monitoring-tools watch --diff --count 6 -- df -h
```

Options: `--interval SECS`, `--count N`, `--diff`, `--json`

---

## Pipe Protocol

All commands support `--json` for structured output compatible with the Skill Foundry pipe protocol:

```bash
# Alert if uptime drops below 95%
monitoring-tools uptime --url https://example.com --count 10 --json | \
  monitoring-tools alert --threshold 95 --below --message "Uptime degraded"

# Dashboard output piped downstream
monitoring-tools dashboard --config ./urls.json --json | some-other-tool
```

## License

MIT