Skip to content
OwloopsPublic

About

Uptime monitoring CLI tool with alerting and advanced settings

Topics

Resources

Contributing

Stars

1.1k stars

Watchers

10 watching

Forks

Latest commit

 

History

196 Commits

Folders and files

Repository files navigation

Updo

Updo

Updo is a command-line tool for monitoring website uptime and performance, with response times, SSL certificate expiry and alerts.

Latest Release Go Reference License: MIT

Updo demo

Features


  Real-time

Uptime percentage, response times and SSL certificate tracking, updated as it runs.



  Multi-target

Watch many URLs at once, from the command line or a TOML config, each with its own interval and rules.



  Multi-region

Deploy probes as AWS Lambda functions across 13 regions to see your site from where your users are.



  Flexible HTTP

Custom headers, POST and PUT bodies, redirect and SSL options, response assertions, IPv4 or IPv6 only checks.



  Alerts

Desktop notifications plus webhooks. Slack and Discord are detected and formatted automatically.



  Output

Interactive TUI, plain text or JSON logs, and Prometheus export for Grafana dashboards and long-term storage.


Table of Contents

Installation

# macOS and Linux, Homebrew
brew install owloops/tap/updo

# Linux and macOS, install script picks the right release asset
curl -sSL https://raw.githubusercontent.com/Owloops/updo/main/install.sh | bash

# Arch Linux
yay -S updo

# Nix, run without installing
nix run github:Owloops/updo -- monitor https://example.com

# Docker, build the image and run it in one line
docker run --rm -it "$(docker build -q https://github.com/Owloops/updo.git)" monitor https://example.com

# Any platform with Go 1.27 or newer
go install github.com/Owloops/updo@latest

Package files

Every release ships native packages for Linux plus tarballs for macOS and an executable for Windows. Grab them from the latest release:

Platform File
Debian, Ubuntu updo_<version>_linux_amd64.deb, dpkg -i
Fedora, RHEL, openSUSE updo_<version>_linux_amd64.rpm, rpm -i or zypper install
Alpine updo_<version>_linux_amd64.apk, apk add --allow-untrusted
Arch updo-bin from the AUR, or the .pkg.tar.zst above
macOS updo_Darwin_arm64, updo_Darwin_x86_64
Windows updo_Windows_x86_64.exe, move it somewhere on your PATH

The install script handles the correct asset, architecture and PATH for you, which is why it is the shortest path on Linux and macOS.

Usage

# Monitor URLs
updo monitor <website-url> [options]
updo monitor <url1> <url2> <url3>

# Using configuration file
updo monitor --config <config-file>

# Generate shell completions
updo completion bash > updo_completion.bash

Options

Basic:

  • --url, --config: Target URL or TOML config file
  • --refresh: Check interval in seconds (default: 5)
  • --timeout: Request timeout in seconds (default: 10)
  • --count: Number of checks (0 = infinite)
  • --simple: Text output instead of TUI

HTTP:

  • --header: Custom HTTP headers (repeatable)
  • --request: HTTP method (default: GET)
  • --data: Request body data
  • --skip-ssl, --follow-redirects, --accept-redirects: SSL and redirect options
  • --assert-text: Expected response text
  • -4, --ipv4 / -6, --ipv6: Restrict checks to one address family

Multi-region:

  • --regions: AWS regions (comma-separated or 'all')
  • --profile: AWS profile for remote executors

Output & Alerts:

  • --log: JSON structured logging
  • --webhook-url, --webhook-header: Webhook notifications
  • --only, --skip: Target filtering

Note

When using CLI flags, all settings (headers, webhook URL, timeouts, etc.) apply globally to all monitored targets. For per-target configuration, use a TOML configuration file.

Examples

# Basic monitoring
updo monitor https://example.com

# Set custom refresh and timeout
updo monitor --refresh 10 --timeout 5 https://example.com

# Simple mode and logging
updo monitor --simple --count 10 https://example.com
updo monitor --log --count 10 https://example.com > output.json

# Custom requests
updo monitor --header "Authorization: Bearer token" --assert-text "Welcome" https://example.com
updo monitor --request POST --header "Content-Type: application/json" --data '{"test":"data"}' https://api.example.com

# Multi-target monitoring
updo monitor https://google.com https://github.com https://cloudflare.com
updo monitor --config example-config.toml --only Google,GitHub

# Multi-region monitoring
updo monitor --regions us-east-1,eu-west-1 https://example.com
updo monitor --regions all --profile production https://example.com

# Webhook notifications
updo monitor --webhook-url "https://hooks.slack.com/services/YOUR/WEBHOOK" https://example.com

Configuration File

Use TOML configuration for complex monitoring setups with multiple targets.

Example Configuration

[global]
refresh_interval = 5
timeout = 10
webhook_url = "https://hooks.slack.com/services/YOUR/WEBHOOK"
only = ["Google", "API"]  # Monitor only these targets

[[targets]]
url = "https://www.google.com"
name = "Google"
refresh_interval = 3
assert_text = "Google"

[[targets]]
url = "https://api.example.com/health"
name = "API"
method = "POST"
headers = ["Authorization: Bearer token"]

Configuration Options

Global settings (apply to all targets unless overridden):

  • refresh_interval, timeout, follow_redirects, accept_redirects, receive_alert, count
  • body_size_limit: Response body cap in bytes (default 1048576 = 1 MiB; 0 means no limit)
  • webhook_url, webhook_headers: Default webhook settings
  • only, skip: Target filtering arrays
  • regions: AWS regions for remote executors

Target settings (can override global):

  • url (required), name: Target identification
  • method, headers, body: HTTP request options
  • assert_text, should_fail: Response validation
  • skip_ssl, follow_redirects, accept_redirects: Connection options
  • body_size_limit: Per-target response body cap (set to 0 to disable capping for this target)
  • webhook_url, webhook_headers: Per-target notifications
  • regions: Target-specific AWS regions

Important

Response bodies are capped at body_size_limit bytes when evaluating assert_text. If your asserted text appears beyond the cap, the assertion fails and the probe logs a warning (visible in the Recent Logs widget in TUI mode, or on stderr in simple mode). Raise body_size_limit or set it to 0 for targets returning large payloads.

Multi-Region Monitoring

Deploy remote executors as AWS Lambda functions across 13 global regions for distributed monitoring from multiple geographic locations.

# Deploy remote executors to AWS regions
updo aws deploy --regions us-east-1,eu-west-1

# Monitor using remote executors
updo monitor --regions us-east-1,eu-west-1 https://example.com

# Cleanup when done
updo aws destroy --regions all

Prerequisites

AWS CLI configured with appropriate credentials and the following permissions:

Service Required Permissions
Lambda CreateFunction, UpdateFunctionCode, DeleteFunction, GetFunction, InvokeFunction
IAM CreateRole, AttachRolePolicy, DetachRolePolicy, DeleteRole, GetRole
STS GetCallerIdentity

Supported regions: us-east-1, us-west-1, us-west-2, eu-west-1, eu-central-1, eu-west-2, ap-southeast-1, ap-southeast-2, ap-northeast-1, ap-northeast-2, ap-south-1, sa-east-1, ca-central-1

Troubleshooting: If you get credential errors, run aws sso login --profile your-profile to refresh expired sessions.

Webhook Notifications

Updo can send webhook notifications when targets go up or down. Updo automatically detects Slack and Discord webhooks by URL pattern and formats messages accordingly with rich formatting. Custom webhooks receive a generic JSON payload.

Supported Platforms

  • Slack - Auto-detected via hooks.slack.com URL, sends rich messages with attachments and color coding
  • Discord - Auto-detected via discord.com/api/webhooks URL, sends embeds with color and structured fields
  • Custom - Any other webhook URL receives generic JSON format

Integration Examples

Slack Webhook (Auto-Detected):

[[targets]]
url = "https://api.example.com"
name = "Production API"
webhook_url = "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"

Updo automatically formats Slack messages with:

  • Color-coded attachments (red for down, green for up)
  • Unicode symbols (✘ for down, ✔ for up)
  • Structured fields for URL, error, status code, response time, and timestamp

Discord Webhook (Auto-Detected):

[[targets]]
url = "https://api.example.com"
name = "Production API"
webhook_url = "https://discord.com/api/webhooks/123456789/YOUR_WEBHOOK_TOKEN"

Updo automatically formats Discord messages with:

  • Color-coded embeds (red for down, green for up)
  • Unicode symbols (✘ for down, ✔ for up)
  • Structured fields with inline formatting
  • Clickable URL links

Custom Webhook:

For custom webhooks, Updo sends a generic JSON payload:

{
  "event": "target_down",
  "target": "Production API",
  "url": "https://api.example.com",
  "timestamp": "2024-01-01T12:00:00Z",
  "response_time_ms": 1500,
  "status_code": 500,
  "error": "Internal Server Error"
}
[[targets]]
url = "https://critical-service.example.com"
name = "Critical Service"
webhook_url = "https://alerts.internal.com/webhook"
webhook_headers = [
  "Authorization: Bearer YOUR_TOKEN",
  "X-Service: updo-monitor"
]

Prometheus & Grafana Integration

Export updo metrics to Prometheus for long-term storage, visualization, and alerting:

# Basic Prometheus integration
updo monitor --prometheus-url http://localhost:9090/api/v1/write https://example.com

# Via environment variables (CLI flag optional if URL provided via env)
export UPDO_PROMETHEUS_RW_SERVER_URL="https://prometheus.example.com/api/v1/write"
export UPDO_PROMETHEUS_USERNAME="admin"
export UPDO_PROMETHEUS_PASSWORD="secret"
updo monitor https://example.com

Available metrics:

  • Target uptime and response times
  • HTTP status codes and timing breakdown (DNS, TCP, TTFB, download)
  • SSL certificate expiry and assertion results

Quick start with Docker:

# Clone and start the monitoring stack
git clone https://github.com/Owloops/updo.git
cd updo/examples/prometheus-grafana
docker compose up -d

Access Grafana at http://localhost:3000 for pre-built dashboards.

updo-multi-region-grafana.mp4

Tip

Full documentation lives in examples/prometheus-grafana/README.md: complete setup, authentication options, metrics reference and PromQL examples.

Structured Logging

The --log flag outputs JSON-formatted logs for programmatic consumption:

  • Check logs (stdout): HTTP requests, responses, and timing information
  • Metrics logs (stdout): Uptime, response time stats, success rate
  • Error logs (stderr): Failures, warnings, and assertion results

Usage examples:

# All logs to one file
updo monitor --log https://example.com > all.json 2>&1

# Metrics to one file, errors to another
updo monitor --log https://example.com > metrics.json 2> errors.json

# Processing with jq
updo monitor --log https://example.com | jq 'select(.type=="check") | .response_time_ms'

Keyboard Shortcuts

In the TUI:

Keys Action
↑ ↓ Move through targets
Tab Collapse or expand every target group
Enter Collapse or expand the selected group
/ Search, Esc to leave search
l Show or hide logs for the selected target
Esc Close the logs panel
q Ctrl+c Quit

Exit Codes

Useful for cron jobs, scripts and CI:

  • 0: every checked target was up
  • 1: at least one target was down or failed its assertion
  • 2: usage or configuration error

Runs stopped with Ctrl+C or q exit with 0, since the run did not finish on its own.

Community

Contributions are welcome. CONTRIBUTING.md covers building, testing, commit style and what a mergeable pull request looks like.

The TUI runs on termui and tcell, which the Owloops fork keeps on a maintained terminal layer.

The project has been featured in awesome-cli-apps, awesome-readme, Terminal Trove and Jupiter Broadcasting.


Built with love by Owloops

About

Uptime monitoring CLI tool with alerting and advanced settings

Topics

Resources

Contributing

Stars

1.1k stars

Watchers

10 watching

Forks

Releases

Used by

Contributors

Languages