Quickstart

perrus-cli quickstart

perrus-cli is a developer-oriented health dashboard that monitors HTTP, TCP, and DNS endpoints using configurable conditions. It is a clean-room Go reimplementation of Gatus designed for agent-first CLI usage.

Setup

# 1. Generate a config file
perrus-cli config-init

# 2. Edit config.yaml — add your endpoints
# 3. Validate the config
perrus-cli config-validate

# 4. Start the dashboard (foreground)
perrus-cli start

# OR as a background daemon
perrus-cli start -daemon

Dashboard is served at http://localhost:8080

Config format

endpoints:
  - name: "my-api"
    url: "https://api.example.com/health"
    interval: "30s"
    conditions:
      - "[STATUS] == 200"
      - "[RESPONSE_TIME] < 500"

  - name: "my-db"
    url: "tcp://db.example.com:5432"
    interval: "60s"
    conditions:
      - "[CONNECTED] == true"

  - name: "dns-check"
    url: "dns://example.com"
    interval: "120s"
    conditions:
      - "[CONNECTED] == true"

Supported URL schemes

Supported conditions

One-shot checks (agent-friendly)

# Check a single endpoint, exit code 0=pass, 2=fail
perrus-cli check -config config.yaml my-api

# Machine-readable JSON output
perrus-cli check -config config.yaml -json my-api

# Check all endpoints and print results
perrus-cli results -config config.yaml -format json

Daemon management

perrus-cli start -daemon              # start background daemon
perrus-cli status                     # check if running
perrus-cli stop                       # stop daemon

Logs: /tmp/perrus-cli.log

API endpoints (when server is running)