Updo is a command-line tool for monitoring website uptime and performance, with response times, SSL certificate expiry and alerts.
|
Uptime percentage, response times and SSL certificate tracking, updated as it runs. |
Watch many URLs at once, from the command line or a TOML config, each with its own interval and rules. |
Deploy probes as AWS Lambda functions across 13 regions to see your site from where your users are. |
|
Custom headers, POST and PUT bodies, redirect and SSL options, response assertions, IPv4 or IPv6 only checks. |
Desktop notifications plus webhooks. Slack and Discord are detected and formatted automatically. |
Interactive TUI, plain text or JSON logs, and Prometheus export for Grafana dashboards and long-term storage. |
- Installation
- Usage
- Configuration File
- Multi-Region Monitoring
- Webhook Notifications
- Prometheus & Grafana Integration
- Structured Logging
- Keyboard Shortcuts
- Exit Codes
- Community
# 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@latestEvery 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.
# 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.bashBasic:
--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.
# 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.comUse TOML configuration for complex monitoring setups with multiple targets.
[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"]Global settings (apply to all targets unless overridden):
refresh_interval,timeout,follow_redirects,accept_redirects,receive_alert,countbody_size_limit: Response body cap in bytes (default1048576= 1 MiB;0means no limit)webhook_url,webhook_headers: Default webhook settingsonly,skip: Target filtering arraysregions: AWS regions for remote executors
Target settings (can override global):
url(required),name: Target identificationmethod,headers,body: HTTP request optionsassert_text,should_fail: Response validationskip_ssl,follow_redirects,accept_redirects: Connection optionsbody_size_limit: Per-target response body cap (set to0to disable capping for this target)webhook_url,webhook_headers: Per-target notificationsregions: 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.
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 allAWS 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.
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.
- Slack - Auto-detected via
hooks.slack.comURL, sends rich messages with attachments and color coding - Discord - Auto-detected via
discord.com/api/webhooksURL, sends embeds with color and structured fields - Custom - Any other webhook URL receives generic JSON format
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"
]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.comAvailable 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 -dAccess 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.
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'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 |
Useful for cron jobs, scripts and CI:
0: every checked target was up1: at least one target was down or failed its assertion2: usage or configuration error
Runs stopped with Ctrl+C or q exit with 0, since the run did not finish on its own.
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 by Owloops