Hookdeck CLI

2.1.1 · active · verified Wed Apr 22

The Hookdeck CLI, currently at stable version 2.1.1, provides a command-line interface for interacting with the Hookdeck platform. It enables developers to manage webhooks locally, forward them to the Hookdeck service, and control various aspects of their Hookdeck account, including connections, issues, and metrics. The project maintains an active release cadence with regular patch and minor updates, often accompanied by beta pre-releases for early testing. Key differentiators include its ability to securely expose local development environments to webhook traffic via the `hookdeck listen` command, manage webhook connections by name or ID, and integrate with the Event Gateway MCP for advanced scenarios. Recent updates have focused on improving authentication flows, gateway reliability, and security patches.

Common errors

```
Error: You are not logged in. Please run 'hookdeck login' to authenticate.
```
cause The user attempted to execute a CLI command that requires authentication without an active login session.

fix Run `hookdeck login` in your terminal to authenticate your Hookdeck CLI session. This will typically open a browser window for you to log in.
```
Error: unknown flag: --config
```
cause The user is attempting to use the deprecated global `--config` flag, which was renamed in v2.0.0.

fix Replace `--config` with `--hookdeck-config` in your command. For example, `hookdeck listen --hookdeck-config ~/.hookdeck/config.json`.
```
Error: listen EADDRINUSE: address already in use :::8080
```
cause The local port specified for `hookdeck listen` (e.g., 8080) is currently being used by another application or process.

fix Either stop the process currently using the desired port, or specify a different available port for `hookdeck listen` (e.g., `hookdeck listen 3000`).

Warnings

breaking The global configuration flag `--config` was renamed to `--hookdeck-config` in v2.0.0 to avoid conflicts with other command-specific flags.
Fix: Update all scripts and commands using the global configuration flag to use `--hookdeck-config` instead of `--config`.
gotcha Version v2.0.2 patched a security vulnerability (GHSA-q382-vc8q-7jhj) related to improper handling of null Unicode characters when parsing JSON within an internal Go SDK dependency. This primarily affected the Event Gateway MCP component.
Fix: Upgrade `hookdeck-cli` to v2.0.2 or a later version to ensure the security patch is applied. Use `npm install -g hookdeck-cli@latest`.
gotcha Starting from v2.1.1, authentication failures (HTTP 401 responses) now provide clearer, more actionable error messages. For `hookdeck gateway mcp`, these messages are directed to `stderr` to maintain clean `stdout` for JSON-RPC clients.
Fix: Review any automation or scripting that parses `hookdeck` CLI output, especially for `hookdeck gateway mcp` commands, to ensure `stderr` is correctly monitored for authentication error messages.

Install

npm install hookdeck-cli npm
yarn add hookdeck-cli yarn
pnpm add hookdeck-cli pnpm

Quickstart

Installs the Hookdeck CLI globally, authenticates the user, and sets up local webhook forwarding.

npm install -g hookdeck-cli

# Log in to your Hookdeck account via browser
hookdeck login

# Listen for webhooks on local port 8080, forwarding them via Hookdeck
# This command sets up a temporary connection to expose your local server
hookdeck listen 8080

view raw JSON →