upp

Table of Contents

• Why Upp?
• Quick Start
• Features
  • Interactive TUI Dashboard
  • Uptime Monitoring with Sparklines
  • Change Detection + Diff
  • Conditional Triggers
  • JSON API Monitoring (jq)
  • Advanced HTTP Options
  • Tags & Organization
  • Quick Ping Diagnostics
  • JSON Output for AI Agents
  • Notifications
  • Daemon Mode
• Check Types
• Target Configuration Fields
• Tutorial: Monitor Your First Website in 60 Seconds
• AI Agent Integration
• How Upp Is Different
• Installation
• All Commands
• Configuration
  • Reference
• Running as a Background Service
• Tech Stack
• Contributing
• License

Why Upp?

You just want to know if your website is up. Maybe get alerted when a pricing page changes. Simple, right?

There are plenty of great monitoring tools out there — dashboards, status pages, change trackers. They work well for what they're built for. But most share a common pattern:

1. Docker or server required — spin up a container, expose a port, manage volumes
2. Web UI only — need a browser to check on things
3. Single purpose — want uptime monitoring and change detection? Run separate services
4. Hard to script — integrating with cron jobs or AI agents means wrestling with REST APIs

For teams running production infrastructure with public status pages, these tools are the right choice. But if you just want to monitor a handful of sites from your terminal — or let an AI agent keep an eye on things — there should be a simpler way.

That's why Upp exists.

One 17MB binary. Works from your terminal. Works over SSH. Works in cron jobs. Works with AI agents out of the box. Install it, add a URL, done. No containers, no web UIs, no port forwarding.

Quick Start

# Install
go install github.com/naru-bot/upp@latest

# Add a site
upp add https://example.com --name "My Site"

# Check it
upp check

# See results
upp status

That's it. You're monitoring a website.

Features

🖥 Interactive TUI Dashboard

Full terminal UI with keyboard navigation. Browse targets, view stats, trigger checks — all without leaving your terminal. Works beautifully over SSH.

upp tui

Navigate with ↑↓/jk, Enter for details, c to check, p to pause, d to delete.

📈 Uptime Monitoring with Sparklines

Track HTTP status codes, response times, availability percentage, and SSL certificate expiry. Response time trends are visualized as sparkline charts right in your terminal.

upp status --period 7d
upp watch --refresh 10    # Live auto-refreshing dashboard

🔍 Change Detection + Diff

Monitor pages for content changes. Target specific elements with CSS selectors. View colored unified diffs of what changed.

upp add https://example.com/pricing --name "Pricing" --selector "div.price"
upp check "Pricing"
upp diff "Pricing"

🎯 Conditional Triggers

Only get notified when specific conditions are met. Reduce alert noise by filtering on content.

# Alert only when "out of stock" appears
upp add https://store.example.com/product --trigger-if "contains:out of stock"

# Alert when "healthy" disappears from status page
upp add https://example.com/status --trigger-if "not_contains:healthy"

# Alert on regex pattern match
upp add https://example.com/pricing --trigger-if "regex:price.*\$[5-9][0-9]"

# Combine with CSS selectors or jq for precise monitoring
upp add https://example.com/api --jq '.status' --trigger-if "not_contains:ok"

Trigger types: contains, not_contains, regex, not_regex

📡 JSON API Monitoring (jq)

Monitor JSON APIs with built-in jq filtering. Extract specific fields before change detection — only track what matters.

# Monitor a specific field in a JSON API
upp add https://api.example.com/v1/status --jq '.services.database.status' --name "DB Status"

# Track price changes from a JSON endpoint
upp add https://api.store.com/product/123 --jq '.price' --name "Product Price"

# Extract nested data
upp add https://api.example.com/data --jq '.items[] | {name, status}' --name "Items"

# Combine with triggers — alert only when price drops below threshold
upp add https://api.store.com/product/123 --jq '.price' --trigger-if "regex:^[0-9]\."

🔐 Advanced HTTP Options

Full control over HTTP requests — method, body, auth, redirects, and status codes.

# POST request with JSON body (API health checks, GraphQL, webhooks)
upp add https://api.example.com/health --method POST --body '{"check":"deep"}'

# Bearer token authentication
upp add https://api.example.com/protected --auth-bearer "your-token-here"

# Basic auth
upp add https://staging.example.com --auth-basic "user:password"

# Monitor that a redirect exists (don't follow it)
upp add https://old.example.com --no-follow --accept-status "301"

# Accept specific status codes as "up" (e.g. 404 page monitoring)
upp add https://example.com/deleted-page --accept-status "200,404"

# Skip TLS verification (self-signed certs on internal services)
upp add https://internal.example.com:8443 --insecure

# Combine everything: POST + auth + jq + trigger
upp add https://api.example.com/graphql \
  --method POST \
  --body '{"query":"{ status { healthy } }"}' \
  --auth-bearer "token" \
  --jq '.data.status.healthy' \
  --trigger-if "not_contains:true"

🏷 Tags & Organization

Organize targets with tags. Filter by tag in the CLI and TUI.

# Tag targets when adding
upp add https://example.com --tag production --tag web

# Tag existing targets
upp tag "My Site" production web
upp untag "My Site" staging

# Filter by tag
upp list --tag production
upp check --tag production
upp list --tags              # show all tags with counts

# TUI: press 't' to cycle tag filter, '/' to search

⚡ Quick Ping Diagnostics

One-off checks without saving anything to the database. Perfect for quick debugging.

upp ping https://api.example.com/health

🤖 JSON Output for AI Agents

Every single command supports --json. Consistent, structured output that's trivial to parse. This is what makes Upp different from every GUI-based monitor.

upp check --json | jq '.[] | select(.status == "down")'

[
  {
    "target": "My Site",
    "url": "https://example.com",
    "status": "up",
    "status_code": 200,
    "response_time_ms": 142,
    "changed": false,
    "ssl_days_left": 85
  }
]

🔔 Notifications

Get alerted on Telegram, Discord, Slack, webhooks, or custom shell commands when things go wrong.

# Telegram
upp notify add --name tg --type telegram \
  --config '{"bot_token":"123:ABC","chat_id":"-100123"}'

# Discord
upp notify add --name discord --type discord \
  --config '{"webhook_url":"https://discord.com/api/webhooks/..."}'

# Webhook (Slack, etc.)
upp notify add --name alerts --type webhook \
  --config '{"url":"https://hooks.slack.com/services/..."}'

# Custom shell command
upp notify add --name logger --type command \
  --config '{"command":"echo \"{target} is {status}\" >> /var/log/upp.log"}'

# Manage
upp notify list
upp notify remove alerts

👻 Daemon Mode

Run Upp as a background service. Checks run on schedule, notifications fire automatically.

upp daemon                      # Foreground
nohup upp daemon &              # Background

See Systemd Service for production setup.

Check Types

Upp supports multiple monitoring approaches for different use cases:

HTTP (default)

• Monitors HTTP/HTTPS endpoints
• Tracks status codes, response times, SSL expiry
• Supports CSS selectors for targeted change detection
• Supports expected keyword matching
• Examples:

  upp add https://example.com --name "My Site"
  upp add https://example.com/pricing --selector "div.price" --name "Pricing"
  upp add https://api.example.com/health --expect "ok" --name "API Health"
  

TCP

• Tests TCP port connectivity
• Example: upp add example.com:3306 --type tcp --name "MySQL"

Ping

• ICMP-style connectivity check
• Example: upp add example.com --type ping --name "Server Ping"

DNS

• DNS resolution check
• Example: upp add example.com --type dns --name "DNS Check"

Visual (screenshot diff)

• Takes screenshots via headless browser and compares pixel-by-pixel
• Configurable threshold percentage (default 5%)
• Requires a headless browser (run upp doctor to check)
• Examples:

  upp add https://example.com --type visual --name "Homepage Visual"
  upp add https://example.com --type visual --threshold 10.0 --name "Loose Visual"
  

WHOIS (domain monitoring)

• Monitors WHOIS data for changes (registrar, nameservers, status)
• Tracks domain expiry and warns when <30 days
• Domain is extracted from URL automatically
• Example:

  upp add https://example.com --type whois --name "Domain WHOIS"
  

Target Configuration Fields

When using the TUI add/edit screen, these fields control how your targets are monitored:

Tutorial: Monitor Your First Website in 60 Seconds

Step 1 — Install Upp:

go install github.com/naru-bot/upp@latest

Step 2 — Add a website to monitor:

upp add https://yoursite.com --name "My App"

Step 3 — Run your first check:

upp check "My App"

You'll see status code, response time, SSL days remaining, and whether content changed.

Step 4 — Set up a notification so you know when it goes down:

upp notify add --name tg --type telegram \
  --config '{"bot_token":"YOUR_BOT_TOKEN","chat_id":"YOUR_CHAT_ID"}'

Step 5 — Start the daemon for continuous monitoring:

upp daemon

Done. You're monitoring a website with notifications. No Docker, no browser, no account signups.

Bonus — Launch the TUI for a beautiful overview:

upp tui

AI Agent Integration

This is Upp's superpower. Every command speaks JSON natively. No API servers, no authentication tokens, no SDK. Just pipe and parse.

Use with AI coding agents

# "Are any of my sites down?"
upp check --json | jq '.[] | select(.status == "down")'

# "Which sites have low uptime?"
upp status --json | jq '.[] | select(.uptime_percent < 99)'

# "Did anything change?"
upp check --json | jq '.[] | select(.changed == true)'

# "Show me the diff"
upp diff "Pricing Page" --json

JSON conventions

• Lists → JSON arrays: [{...}, {...}]
• Single items → JSON objects: {...}
• Errors → {"error": "message"}
• Timestamps → RFC3339 format

Cron integration

# Check every 5 minutes, email on failures
*/5 * * * * upp check --json | jq -e '.[] | select(.status == "down")' && \
  echo "ALERT" | mail -s "Site down" admin@example.com

How Upp Is Different

Installation

Go install (recommended)

go install github.com/naru-bot/upp@latest

Requires Go 1.24+.

Binary releases

curl -LO https://github.com/naru-bot/watchdog/releases/latest/download/watchdog_darwin_arm64.tar.gz
tar xzf upp_darwin_arm64.tar.gz
sudo mv upp /usr/local/bin/

curl -LO https://github.com/naru-bot/watchdog/releases/latest/download/watchdog_darwin_amd64.tar.gz
tar xzf upp_darwin_amd64.tar.gz
sudo mv upp /usr/local/bin/

curl -LO https://github.com/naru-bot/watchdog/releases/latest/download/watchdog_linux_amd64.tar.gz
tar xzf upp_linux_amd64.tar.gz
sudo mv upp /usr/local/bin/

curl -LO https://github.com/naru-bot/watchdog/releases/latest/download/watchdog_linux_arm64.tar.gz
tar xzf upp_linux_arm64.tar.gz
sudo mv upp /usr/local/bin/

Build from source

git clone https://github.com/naru-bot/watchdog.git
cd upp
make build
sudo mv upp /usr/local/bin/

Cross-compilation

make cross
# Produces: upp-darwin-arm64, upp-darwin-amd64, upp-linux-amd64, upp-linux-arm64

All Commands

Global Flags

Add command flags

upp add <url> [flags]
  --name         Target name (auto-generated from URL if omitted)
  --type         Check type: http, tcp, ping, dns, visual, whois (default: http)
  --interval     Check interval in seconds (default: 300)
  --selector     CSS selector for change detection (http type)
  --expect       Expected keyword in response body (http type)
  --timeout      Request timeout in seconds (default: 30)
  --retries      Retry count before marking as down (default: 1)
  --threshold    Visual diff threshold percentage (visual type, default: 5.0)

Configuration

upp init    # Creates ~/.config/upp/config.yml

Config file location: ~/.config/upp/config.yml (or $XDG_CONFIG_HOME/upp/config.yml)

Full example

defaults:
  interval: 300
  type: http
  timeout: 30
  retry_count: 1
  user_agent: upp/1.0

display:
  color: true
  format: table
  verbose: false

thresholds:
  ssl_warn_days: 30

headers:
  Authorization: Bearer my-token
  X-Custom: value

Reference

defaults — Default values for new targets

display — Output formatting

thresholds — Warning thresholds

headers — Custom HTTP headers

Key-value pairs added to every HTTP request. Useful for authentication tokens, custom identifiers, or bypassing certain WAF rules.

headers:
  Authorization: Bearer my-api-token
  Accept-Language: en-US

Data storage

All data lives in ~/.upp/upp.db (SQLite). Back up by copying the file, query with any SQLite client, or export via upp export.

Running as a Background Service

To run Upp in the background and survive reboots, set it up as a systemd service.

One-liner setup:

sudo tee /etc/systemd/system/upp-monitor.service << 'EOF'
[Unit]
Description=Upp Website Monitor
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/upp daemon
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable --now upp-monitor

Check status:

sudo systemctl status upp-monitor

View logs:

journalctl -u upp-monitor -f

Stop / restart:

sudo systemctl stop upp-monitor
sudo systemctl restart upp-monitor

Removing the Service

sudo systemctl stop upp-monitor
sudo systemctl disable upp-monitor
sudo rm /etc/systemd/system/upp-monitor.service
sudo systemctl daemon-reload

Uninstalling Upp

To completely remove Upp from your system:

# 1. Stop and remove the service (if running)
sudo systemctl stop upp-monitor
sudo systemctl disable upp-monitor
sudo rm /etc/systemd/system/upp-monitor.service
sudo systemctl daemon-reload

# 2. Remove the binary
sudo rm /usr/local/bin/upp
# Or if installed via go install:
rm $(go env GOPATH)/bin/upp

# 3. Remove data and config
rm -rf ~/.upp
rm -rf ~/.config/upp

Tech Stack

Built with some excellent Go libraries:

• Cobra — CLI framework
• Bubbletea + Bubbles + Lipgloss — TUI
• modernc.org/sqlite — Pure Go SQLite (zero CGO)
• goquery — HTML parsing
• Custom LCS-based line diff engine

Contributing

Contributions welcome! Open an issue or PR on GitHub.

git clone https://github.com/naru-bot/watchdog.git
cd upp
make build
# hack away

License

MIT