CLI

thump is a zero-dependency command-line client for the thump API. Check status, force-run probes, and list incidents without leaving the terminal — plus the private-network agent for endpoints our cloud probes can't reach.

Install

From the repo (npm publish is coming):

pnpm --filter @thump/cli build
node apps/cli/dist/main.js help

Link it as thump on your PATH:

cd apps/cli && npm link

Requires Node 20+. No runtime dependencies.

Authenticate

Create a personal access token in the dashboard under Settings → API tokens, then:

thump login --token thump_pat_…

The token is validated against the API and saved to ~/.config/thump/config.json (mode 0600). Alternatives that skip the saved config:

• THUMP_TOKEN environment variable
• --token on any command

Self-hosted instances: add --api-url https://your-instance.dev to login (persisted) or any command (one-off).

Commands

thump status                 account overview: totals + recent incidents
thump monitors               list monitors
thump run <id>               force-run a monitor in every region
thump incidents <id>         list a monitor's incidents (--status open|resolved|all)
thump whoami                 show the authenticated user
thump plan -f <file>         show what apply would change
thump apply -f <file>        reconcile monitors to a spec file
thump agent                  private-network agent (see the guide)

Monitor ids accept an unambiguous prefix — thump run 0f8b7c62 works as long as only one monitor starts with it.

Monitors as code

Declare the monitors you want in a file and reconcile the account to match. YAML and JSON are both accepted.

# monitors.yaml
monitors:
  - name: Public API
    url: https://api.example.com/health
    intervalSeconds: 60
    regions: [wnam, enam]
    tags: [prod, api]
    assertions:
      - type: status_code
        operator: eq
        expected: 200
      - type: response_time_ms
        operator: lt
        expected: 2000

  - name: Marketing site
    url: https://example.com
    intervalSeconds: 300
    regions: [weur]

thump plan  -f monitors.yaml      # show the diff, change nothing
thump apply -f monitors.yaml      # prompt, then apply
thump apply -f monitors.yaml --yes    # non-interactive (CI)

  ~ update  Public API
              intervalSeconds: 300 → 60
  + create  Marketing site
              GET https://example.com

Plan: 1 to create, 1 to update, 0 to delete (3 unchanged)

Monitors are matched by name. It's the key you write, so renaming one in the file reads as a delete plus a create rather than a silent rewrite.

Nothing is deleted unless you ask. A spec file is usually a partial view of an account, so monitors that exist but aren't in the file are left alone. Pass --prune to have apply remove them — the plan lists every deletion before anything happens.

Applying twice in a row is a no-op: the second run reports "No changes."

Fields

Unknown fields are an error rather than being ignored — a typo'd interval would otherwise leave the monitor on the default cadence while the file claims otherwise.

Assertion order matters (it decides which failure is reported as the cause), so reordering them is a real change. Region order does not.

YAML support

The CLI ships with zero dependencies, so it reads a deliberately small YAML subset: mappings, block sequences, inline [a, b] sequences, quoted and plain scalars, and comments. Anchors, aliases, merge keys, tags, block scalars (|, >), flow mappings ({}) and multi-document files are rejected with a line number rather than guessed at. Use JSON if you need anything richer.

JSON output

Every read command takes --json for machine-readable output:

thump monitors --json | jq '.[] | select(.enabled) | .url'

Exit codes

thump run + exit code 2 makes a serviceable deploy gate in any CI system — or use the ready-made GitHub Action.