API
CLI & Monitoring as Code
Define uptime monitors in hopbits.yaml, preview zero-side-effect diffs with hopbits plan, reconcile from CI/CD, and run global HTTP, DNS, traceroute, and MTR probes from your terminal.
On this page
Install the CLI
The hopbits CLI (0.2.0) is a single static binary for Linux, macOS, and Windows with zero runtime dependencies. Every download is verified against SHA256SUMS before installation. The CLI is open source (Apache-2.0) in cli/ on GitHub (CuriAtore/hopbits), with reproducible release binaries and SHA256SUMS.txt published on GitHub Releases (v0.2.5).
curl -fsSL https://hopbits.io/cli.sh | sh
hopbits.io/cli.sh detects your OS and CPU architecture (amd64 or arm64), verifies the SHA-256 digest, and installs hopbits to /usr/local/bin when writable or $HOME/.local/bin otherwise, so it runs without password prompts in CI runners and user shells. Pin a release with HOPBITS_CLI_VERSION=0.2.0 or choose a folder with HOPBITS_INSTALL_DIR.
# Choose: hopbits-linux-amd64, hopbits-linux-arm64, hopbits-darwin-arm64, hopbits-darwin-amd64
BIN="hopbits-linux-amd64"
curl -fsSLO "https://hopbits.io/releases/$BIN"
curl -fsSLO "https://hopbits.io/releases/SHA256SUMS"
# Verify checksum (use 'shasum -a 256' on macOS if sha256sum is absent)
grep " $BIN$" SHA256SUMS | sha256sum -c -
chmod 0755 "$BIN" && mv "$BIN" ~/.local/bin/hopbits
Invoke-WebRequest -Uri "https://hopbits.io/releases/hopbits-windows-amd64.exe" -OutFile "hopbits.exe"
Invoke-WebRequest -Uri "https://hopbits.io/releases/SHA256SUMS" -OutFile "SHA256SUMS"
Get-FileHash .\hopbits.exe -Algorithm SHA256
.\hopbits.exe version
Authenticate
Create a hb_live_... key under Keys & domains in the Console (see API keys). In CI/CD, export HOPBITS_API_KEY; on a workstation, run hopbits login to verify your key and store it with mode 0600 in ~/.config/hopbits/credentials (%APPDATA%\hopbits\credentials on Windows).
# CI/CD and scripts (HOPBITS_KEY and --api-key are also accepted)
export HOPBITS_API_KEY="hb_live_..."
# Or save credentials interactively on your machine
hopbits login
# Inspect credit balance, active monitor count, and live online network nodes
hopbits whoami
Adopt existing Console monitors
Already running monitors created in the web Console? Export them directly into hopbits.yaml and attach declarative key slugs in place with --adopt:
hopbits export --adopt -o hopbits.yaml
--adopt assigns each unkeyed monitor a clean slug via PATCH /v1/checks/{id} before writing hopbits.yaml. Subsequent hopbits apply runs update those monitors in place without recreating them or losing 24-hour uptime telemetry and incident history. Omit --adopt to export a read-only snapshot without modifying existing checks.
hopbits.yaml format & secret interpolation
Commit hopbits.yaml (or hopbits.json) alongside your service code. String values expand ${ENV_VAR} and ${ENV_VAR:-default} from the environment at load time (never inside # comments) and fail fast if a referenced variable is unset or empty without a default, so CI never deploys a blank webhook secret.
version: 1
monitors:
- key: checkout-api
name: Checkout API
type: http
method: GET
target: https://api.example.com/healthz
interval: 1m # 30s and 60s/1m require a verified target
locations: [DE, US, SG]
alert_email: true
webhook_url: https://hooks.example.com/hopbits
webhook_secret: ${HOPBITS_WEBHOOK_SECRET}
- key: marketing-site
name: Marketing Site
type: http
method: HEAD
target: https://www.example.com
interval: 5m # 5m (default), 10m, 15m, 30m and 1h work on any target
locations: [ANY]
- key: status-archive
name: Hourly Status Check
type: http
target: status.example.com
interval: 1h
locations: [DE, US]
- key: edge-gateway-tcp
name: Edge Gateway TLS Port
type: tcp
target: gw.example.com
port: 443
interval: 5m
locations: [DE, GB, US]
| Field | Required | What it does |
|---|---|---|
key | Yes | Stable unique slug (1..63 lowercase letters, digits, - or _, starting and ending with [a-z0-9]). Displayed as a monospace badge in the Console. |
name | No | Display title in the Console and alerts (defaults to key). |
type | No | http (default), tcp (tcp_connect), or icmp (icmp_ping). |
target | Yes | Hostname, IP address, or http(s)://host[:port][/path] URL (host, port, and path are extracted automatically on http unless overridden). |
interval | No | 5m (300s) by default. 5m, 10m, 15m, 30m, and 1h (3600s max) work on all targets; 30s and 1m (60s) require a verified target. Also accepts interval_seconds. |
locations | No | 1 to 3 ISO country codes ([DE, US, SG]) or [ANY] (default). |
method, path, port, family | No | HTTP method (HEAD or verified GET), URL path, TCP/HTTP port, and IP family (ipv4 or ipv6). |
alert_email | No | Boolean (true by default). Sends outage and recovery emails. |
webhook_url, webhook_secret | No | HTTPS port-443 webhook endpoint and HMAC signing secret. Omitting webhook_secret when webhook_url is unchanged preserves an existing secret on the server. |
paused | No | Boolean (false by default). Removing paused: true from YAML unpauses the monitor on the next apply. |
Plan & apply workflow
Run hopbits plan in pull requests to validate every check and preview exact field diffs and daily credit burn via POST /v1/checks/plan with zero side effects. Run hopbits apply on merge to reconcile changes idempotently.
# Zero-side-effect dry-run diff (--detailed-exitcode exits 2 when changes are pending)
hopbits plan -f hopbits.yaml --prune
# Reconcile creates, in-place updates, and stale-key deletions
hopbits apply -f hopbits.yaml --prune
CI/CD post-deploy gate & network diagnostics with hopbits probe
hopbits probe (hopbits 0.2.0+) dispatches an on-demand measurement (http, tcp, icmp, dns, traceroute, or mtr) across real residential, datacenter, or mobile vantages, waits synchronously for per-node results, and exits 1 if HTTP status, p95 latency, or minimum healthy vantage count fails your threshold.
hopbits probe https://api.example.com/healthz \
--from DE,US,SG \
--network residential \
--expect-status 200 \
--max-p95 500ms
# Compare what local ISP resolvers return across countries (or pass --resolver 1.1.1.1 --qtype MX)
hopbits probe _dmarc.example.com --type dns --qtype TXT --resolver isp --from DE,US,NL
# Trace the hop-by-hop network path with router ASN and city enrichment
hopbits probe example.com --type traceroute --proto udp --max-hops 24 --from DE,US
# Measure multi-cycle per-hop packet loss and jitter (2 credits/vantage)
hopbits probe example.com --type mtr --cycles 5 --proto udp --from DE,US
| Flag | What it controls |
|---|---|
--from | Comma-separated ISO country codes (for example DE,US,SG) or ANY. |
--network | Vantage network class: any (default), residential, datacenter, or mobile. |
--type, --method, --path, --port, --family | Probe kind (http, tcp, icmp, dns, traceroute, mtr), HTTP method, path, port (http/tcp), and ipv4 or ipv6. |
--qtype, --resolver, --proto | For --type dns: record type (A, AAAA, CNAME, MX, TXT, NS, SOA, CAA, PTR), resolver (isp, 1.1.1.1, 8.8.8.8, 9.9.9.9, 208.67.222.222), and transport (udp or tcp). |
--max-hops, --cycles | For --type traceroute and --type mtr: hop limit (4..30, default 24), protocol via --proto udp|icmp, and MTR probe cycles (3..10, default 5). |
--expect-status | Required HTTP status code (for example 200); exits 1 if any HTTP response differs. |
--max-p95 | Maximum allowed p95 latency (for example 400ms or 1s); exits 1 if exceeded. |
--min-ok, --limit, --max-credits, --wait | Minimum successful probes required (default 1), nodes per country, credit guard, and synchronous wait window (1..25s). |
--json | Machine-readable JSON output for custom pipeline scripts. |
GitHub Actions workflow
Store HOPBITS_API_KEY (and optional HOPBITS_WEBHOOK_SECRET) in your repository's Actions secrets, then add .github/workflows/hopbits.yml to reconcile hopbits.yaml and verify your live deployment from real user networks:
name: Hopbits Monitoring & Post-Deploy Gate
on:
push:
branches: [main]
workflow_dispatch:
jobs:
hopbits:
runs-on: ubuntu-latest
env:
HOPBITS_API_KEY: ${{ secrets.HOPBITS_API_KEY }}
HOPBITS_WEBHOOK_SECRET: ${{ secrets.HOPBITS_WEBHOOK_SECRET }}
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Install verified Hopbits CLI
run: |
curl -fsSL https://hopbits.io/cli.sh | sh
echo "$HOME/.local/bin" >> "$GITHUB_PATH"
- name: Reconcile declarative monitors
run: hopbits apply -f hopbits.yaml --prune
- name: Verify live production endpoint across regions
run: |
hopbits probe https://api.example.com/healthz \
--from DE,US,SG \
--network residential \
--expect-status 200 \
--max-p95 500ms