CLI Tool

The HookReplay CLI connects your local development server to receive replayed webhooks.

Installation

npm (Recommended)

Install globally via npm:

terminal 
npm install -g hookreplay

npx (No Installation)

Run directly without installing:

terminal 
npx hookreplay

Interactive Commands

The HookReplay CLI is an interactive application. Start it by running hookreplay and use these commands:

Command Description
connect Connect to HookReplay server
disconnect Disconnect from server
status Show connection status
config Manage configuration (api-key, server)
history Show received request history
replay <number> Replay a request from history
version Show version and system info
update Check for and install updates
clear Clear the screen
help Show help message
quit Exit the CLI

config

Configure the CLI settings. Your configuration is saved to ~/.hookreplay/config.json.

Examples 
# View current config
config

# Set API key
config api-key hr_xxxxxxxxxxxx

# Set custom server URL (optional)
config server https://hookreplay.dev

connect

Connect to the HookReplay server. Requires an API key to be configured first.

terminal 
● hookreplay> connect
✓ Connected! Waiting for replay requests...

replay

Replay a request from your local history to a target URL.

terminal 
# View history first
history

# Replay request #1 to a specific URL
replay 1 http://localhost:3000/webhook

Usage Example

Here's a complete workflow using the CLI:

terminal 
$ hookreplay

██╗  ██╗ ██████╗  ██████╗ ██╗  ██╗██████╗ ███████╗██████╗ ██╗      █████╗ ██╗   ██╗
██║  ██║██╔═══██╗██╔═══██╗██║ ██╔╝██╔══██╗██╔════╝██╔══██╗██║     ██╔══██╗╚██╗ ██╔╝
...

v1.0.0  Catch, inspect, and replay webhooks locally

Type help for available commands, or quit to exit.

● hookreplay> config api-key hr_abc123xyz
✓ API key saved!

● hookreplay> connect
Connecting to https://hookreplay.dev...
✓ Connected! Waiting for replay requests...

● hookreplay>
>>> Received ReplayRequest from server!
────────────── Incoming Request #1 ──────────────
│ Method │ POST                                 │
│ Target │ http://localhost:3000/api/webhook    │
│ Headers│ 5 headers                            │
│ Body   │ 1247 chars                           │
Response: 200 OK (145ms)
──────────────────────────────────────────────────

● hookreplay> history
┌───┬────────┬───────────────────────────────────┬───────────┐
│ # │ Method │ Target                            │ Body      │
├───┼────────┼───────────────────────────────────┼───────────┤
│ 1 │ POST   │ http://localhost:3000/api/webhook │ 1247 chars│
└───┴────────┴───────────────────────────────────┴───────────┘

● hookreplay> replay 1 http://localhost:4000/webhook
Replaying request #1 to http://localhost:4000/webhook...
Response: 200 OK (89ms)

Troubleshooting

Connection Issues

If the CLI can't connect:

  • Verify your API key is correct using config
  • Check your internet connection
  • Run status to see current connection state
  • Ensure no firewall is blocking outbound connections

Forwarding Errors

If webhooks aren't reaching your server:

  • Make sure your local server is running before triggering replay
  • Verify the target URL is correct when replaying
  • Check that your server is accepting the correct HTTP method at that endpoint
  • Use history to view received requests and their details

SSL Certificate Errors

The CLI automatically bypasses SSL verification for localhost URLs. For other local HTTPS servers with self-signed certificates, use HTTP instead during development.

Config Issues

Configuration is stored in ~/.hookreplay/config.json. If you experience issues, you can:

  • Check current config with the config command
  • Reset by deleting the config file and reconfiguring