HookWatch CLI reference

hookwatch is a single binary that does three things, each a real client of the workspace API — there is no offline demo. Watch your deliveries in a terminal dashboard, tunnel a hosted endpoint to a process on your machine while you build, or serve your webhooks to an AI assistant over MCP. Every command authenticates with a workspace API key (hwk_…).

Install

curl -fsSL https://get.hookwatch.dev/install.sh | sh

macOS and Linux, amd64 and arm64 (no Windows build yet). Installs to /usr/local/bin (falls back to ~/.local/bin). You can also build from source with Go — go run ./cmd/hookwatch from the cli/ directory.

Authenticate

Mint a workspace key in the dashboard (Settings → Tokens), then give it to the CLI one of three ways — later sources win:

export HOOKWATCH_API_KEY=hwk_…
export HOOKWATCH_SERVER=https://api.hookwatch.dev   # optional — this is the default

On its first run in a terminal, hookwatch and hookwatch tunnel prompt for a key and save it, so you only paste it once. The key never leaves your machine except as a Bearer token to your HookWatch server.

Commands

Live dashboard

Run it with no arguments:

hookwatch          # prompts for a workspace key on first run

The dashboard is a live view of your workspace’s deliveries: a stream of received webhooks with their status, response code, and latency, and a detail view with the full payload, headers, and attempt history — the same data as the web dashboard, in your terminal. Open a delivery to inspect it, or replay and retry a failed one without leaving the feed.

Local-dev tunnel

A tunnel-mode endpoint receives webhooks at a public HookWatch URL and forwards each one, over a WebSocket the CLI holds open, to a URL on your machine — so a provider can reach localhost while you build a handler, with every delivery captured and replayable.

hookwatch tunnel \
  --endpoint ep_… \
  --to http://localhost:3000/webhooks

Point the provider (or your own test) at the endpoint’s public URL. Each delivery is forwarded to --to, and the response your local handler returns is reported back. Add --headless to print one log line per delivery instead of the TUI — handy in CI or a background terminal.

MCP server

Serve the workspace API to an AI assistant over stdio:

HOOKWATCH_API_KEY=hwk_… hookwatch mcp

This is the local (stdio) transport behind the MCP integration — that page has ready-to-paste configs for Claude, Cursor, VS Code, and others, plus the remote HTTP option if you’d rather not run a local binary.

Configuration

Resolution order, lowest priority first:

built-in default  →  ~/.config/hookwatch/config.toml  →  env (HOOKWATCH_*)  →  flags (--server / --key)

Only the server URL has a built-in default (https://api.hookwatch.dev); the key must come from one of the other three. The config file is optional:

# ~/.config/hookwatch/config.toml
server_url = "https://api.hookwatch.dev"   # optional — omit to use the default
api_key    = "hwk_…"

Every command also accepts --server, --key, and --config <path> to override the file and environment for a single run — point the CLI at a self-hosted server or a scratch config without touching your defaults.