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).

Zero-prompt POSIX installer
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.

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).

Environment variable or local login
# 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:

Export and adopt in place
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.

hopbits.yaml
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]
FieldRequiredWhat it does
keyYesStable unique slug (1..63 lowercase letters, digits, - or _, starting and ending with [a-z0-9]). Displayed as a monospace badge in the Console.
nameNoDisplay title in the Console and alerts (defaults to key).
typeNohttp (default), tcp (tcp_connect), or icmp (icmp_ping).
targetYesHostname, IP address, or http(s)://host[:port][/path] URL (host, port, and path are extracted automatically on http unless overridden).
intervalNo5m (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.
locationsNo1 to 3 ISO country codes ([DE, US, SG]) or [ANY] (default).
method, path, port, familyNoHTTP method (HEAD or verified GET), URL path, TCP/HTTP port, and IP family (ipv4 or ipv6).
alert_emailNoBoolean (true by default). Sends outage and recovery emails.
webhook_url, webhook_secretNoHTTPS port-443 webhook endpoint and HMAC signing secret. Omitting webhook_secret when webhook_url is unchanged preserves an existing secret on the server.
pausedNoBoolean (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.

Preview diffs and reconcile
# 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.

Verify live reachability and p95 latency from residential ISPs
hopbits probe https://api.example.com/healthz \
  --from DE,US,SG \
  --network residential \
  --expect-status 200 \
  --max-p95 500ms
DNS lookup, traceroute, and MTR path & loss diagnostics (hopbits 0.2.0)
# 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
FlagWhat it controls
--fromComma-separated ISO country codes (for example DE,US,SG) or ANY.
--networkVantage network class: any (default), residential, datacenter, or mobile.
--type, --method, --path, --port, --familyProbe kind (http, tcp, icmp, dns, traceroute, mtr), HTTP method, path, port (http/tcp), and ipv4 or ipv6.
--qtype, --resolver, --protoFor --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, --cyclesFor --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-statusRequired HTTP status code (for example 200); exits 1 if any HTTP response differs.
--max-p95Maximum allowed p95 latency (for example 400ms or 1s); exits 1 if exceeded.
--min-ok, --limit, --max-credits, --waitMinimum successful probes required (default 1), nodes per country, credit guard, and synchronous wait window (1..25s).
--jsonMachine-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:

.github/workflows/hopbits.yml
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