@hookmetry/cli

@hookmetry/cli

The official CLI for Hookmetry — the Event Failure Intelligence Platform. Tunnel webhooks to localhost, inspect live forensic timelines, and get Hookmetry AI-powered code fixes directly in your terminal.

Installation

npm install -g @hookmetry/cli

Authentication

Before using the CLI, link it to your Hookmetry account:

hookmetry login

Get your CLI token from Dashboard → Settings → CLI Token and paste it when prompted. Your token is saved to ~/.hookmetry/config.json.

---

Commands

hookmetry listen — Tunnel Webhooks to Localhost

Expose a local port to the internet with your persistent Hookmetry endpoint URL:

hookmetry listen --port 3000
# or specify an endpoint directly
hookmetry listen --endpoint ep_abc123 --port 8080

How it works:

• Opens a WebSocket tunnel to your Hookmetry endpoint
• All incoming webhooks are forwarded byte-for-byte to your local server
• Signatures are validated at the Hookmetry edge before forwarding
• Responses are logged with status codes and latency

---

hookmetry diagnose <logId> — Forensic Reconstruction Timeline (New in v1.1.0)

Fetch and render the full step-by-step reconstruction timeline for a failed webhook log:

hookmetry diagnose wl_abc123def456

Output includes:

• / result for each validation step (signature extraction, HMAC computation, timestamp check, etc.)
• Detected provider (Stripe, GitHub, Shopify, etc.) and confidence score
• Matched root cause pattern with diagnosis and severity
• Destination layer result (HTTP status, duration, error message)

Example output:

🔬 Hookmetry AI — Diagnostic Report
Fetching reconstruction timeline for log: wl_abc123...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Log ID:      wl_abc123def456
  Received:    8/8/2026, 8:30:00 PM
  Provider:    stripe
  Status:      ❌ INVALID
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  📋 Reconstruction Timeline:

    [1] ✔  Extract Signature Header
    [2] ✔  Parse Stripe Signature Format (t=...,v1=...)
    [3] ✔  Validate Timestamp (within 5-minute window)
    [4] ✔  Prepare Secret Key
    [5] ✘  HMAC-SHA256 Match — Signature does not match. Body was likely parsed JSON instead of raw bytes.

  🎯 Root Cause Identified:

    Issue:      stripe/parsed_body_mismatch
    Diagnosis:  Body was parsed as JSON before validation. Stripe requires the raw, unparsed request body.
    Severity:   error
    Source:     known_pattern

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  💡 Run `hookmetry explain wl_abc123def456` to get Hookmetry AI code fixes.

---

hookmetry explain <logId> — Hookmetry AI Analysis & Code Fixes (New in v1.1.0)

Invoke Hookmetry AI to generate a precise root cause explanation and copy-paste code fixes for all major languages:

hookmetry explain wl_abc123def456

Output includes:

• Plain-English root cause explanation from Hookmetry AI
• Exact code fixes for Node.js, Python, Java/Spring Boot, and Go

Note: AI Analysis (explain) includes a lifetime trial of 3 free requests for all users! Pro plans receive 100 requests per month, and Team/Business plans include unlimited access. The diagnose command is available on all paid plans.

Example output:

🤖 Hookmetry AI — Intelligent Analysis
Analyzing log wl_abc123...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Provider:    stripe
  Error:       SIGNATURE_MISMATCH
  Analyzed:    8/8/2026, 8:30:05 PM

  🧠 Hookmetry AI Analysis:

  The signature mismatch occurred because Express.js parsed the request body
  as JSON before Stripe's signature validation could access the raw bytes.

  📋 Code Fixes:

  ── Node.js ───────────────────────────────────────────────────
    // Use express.raw() for Stripe webhook routes, NOT express.json()
    app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
      const sig = req.headers['stripe-signature'];
      const event = stripe.webhooks.constructEvent(req.body, sig, process.env.STRIPE_SECRET);
      // ...
    });

  ── Python ────────────────────────────────────────────────────
    # Use request.data (raw bytes), NOT request.json
    payload = request.data
    sig_header = request.headers.get('Stripe-Signature')
    event = stripe.Webhook.construct_event(payload, sig_header, endpoint_secret)

---

hookmetry endpoints — List Your Endpoints

hookmetry endpoints

Displays a table of all your active Hookmetry endpoints with their IDs, names, validation type, and request counts.

---

hookmetry status — Check Authentication

hookmetry status

Shows your authentication status, API connectivity, and the number of active endpoints.

Why Hookmetry CLI?

Traditional debugging requires opening the dashboard, finding the log, and reading JSON. Hookmetry CLI brings your intelligence layer directly to your terminal:

• diagnose — See exactly which validation step failed and why, without opening a browser
• explain — Get AI-generated code fixes in your language of choice, inline in your shell
• listen — Persistent, secure tunneling with edge signature validation

---

Need Help?

• Full documentation: https://hookmetry.com/docs
• Dashboard: https://hookmetry.com/dashboard