beacon

lightweight endpoint uptime monitor for the terminal. no cloud dashboard, no SaaS, just a CLI that tells you if your stuff is up.

install

pip install -e .

quick start

probe a single URL:

beacon ping https://example.com

  ●  example.com                     42.3ms  200

continuous monitoring

create a config file:

beacon init -o config.json

{
  "targets": [
    {"name": "api", "url": "https://api.example.com/health", "interval": 30},
    {"name": "web", "url": "https://example.com", "interval": 60},
    {"name": "cdn", "url": "https://cdn.example.com/test.png", "interval": 120}
  ],
  "db_path": "beacon.db"
}

start monitoring:

beacon watch -c config.json

status summary

beacon status

  api
    uptime  99.87%  avg  43.2ms
     ▁▂▂▃▂▁▂▃▄▃▂▁▁▂▃▂▁▂▃▂▁▁▂▃▂

  web
    uptime  100.00%  avg  128.5ms
     ▃▃▄▃▃▂▃▃▄▅▄▃▃▃▄▃▃▂▃▃▄▃▃▂▃

probe history

beacon history api -n 10

features

• async HTTP probing with configurable timeout and method
• SQLite-backed history with uptime and latency queries
• terminal sparkline latency visualization
• color-coded status output (green < 200ms, yellow < 1s, red > 1s)
• configurable alert thresholds
• magic byte file type detection for response bodies
• zero dependencies beyond httpx

license

MIT