Hookdeck CLI

Using the Hookdeck CLI, you can forward your events (e.g. webhooks) to your local web server with unlimited free and permanent event URLs. Your event history is preserved between sessions and can be viewed, replayed, or used for testing by you and your teammates.

Hookdeck CLI is compatible with most of Hookdeck's features, such as filtering and fan-out delivery. You can use Hookdeck CLI to develop or test your event (e.g. webhook) integration code locally.

You can also manage Hookdeck Event Gateway resources—sources, destinations, connections, events, transformations—from the CLI. For AI and agent workflows, the Event Gateway MCP server (hookdeck gateway mcp) exposes these capabilities as tools in MCP-compatible clients (e.g. Cursor, Claude).

Although it uses a different approach and philosophy, it's a replacement for ngrok and alternative HTTP tunnel solutions.

Hookdeck for development is completely free, and we monetize the platform with our production offering.

For a complete reference of all commands and flags, see REFERENCE.md.

Table of contents

• Installation
  • NPM
  • macOS
  • Windows
  • Linux Or without package managers
  • Docker
• Usage
• Commands
  • Login
  • Listen
  • Logout
  • Skip SSL validation
  • Disable health checks
  • Version
  • Completion
  • Running in CI
  • Event Gateway
  • Event Gateway MCP
  • Manage connections
  • Transformations
  • Requests, events, and attempts
  • Manage active project
  • Telemetry
• Configuration files
• Global Flags
• Troubleshooting
• Developing
• Testing
• Releasing
• Repository Setup
• License

Quick links: Local development (Listen) · Resource management (CLI) / Manage connections · AI / agent integration (Event Gateway MCP)

https://github.com/user-attachments/assets/7a333c5b-e4cb-45bb-8570-29fafd137bd2

Installation

Hookdeck CLI is available for macOS, Windows, and Linux for distros like Ubuntu, Debian, RedHat, and CentOS.

NPM

Hookdeck CLI is distributed as an NPM package:

npm install hookdeck-cli -g

To install a beta (pre-release) version:

npm install hookdeck-cli@beta -g

macOS

Hookdeck CLI is available on macOS via Homebrew in homebrew-core:

brew install hookdeck

New stable versions are picked up automatically by Homebrew's autobump after each release — brew upgrade will pull them in.

To install a beta (pre-release) version from our tap:

brew install hookdeck/hookdeck/hookdeck-beta

[!NOTE] When HOMEBREW_REQUIRE_TAP_TRUST becomes the default in Homebrew 5.2.0 / 6.0.0, installing the beta formula from a third-party tap will require an explicit trust step:

brew trust --formula hookdeck/hookdeck/hookdeck-beta

The stable hookdeck formula lives in homebrew-core and is not affected.

Windows

Hookdeck CLI is available on Windows via the Scoop package manager:

scoop bucket add hookdeck https://github.com/hookdeck/scoop-hookdeck-cli.git
scoop install hookdeck

To install a beta (pre-release) version:

scoop install hookdeck-beta

Linux Or without package managers

To install the Hookdeck CLI on Linux without a package manager:

1. Download the latest linux tar.gz file from https://github.com/hookdeck/hookdeck-cli/releases/latest
2. Unzip the file: tar -xvf hookdeck_X.X.X_linux_amd64.tar.gz
3. Run the executable: ./hookdeck

For beta (pre-release) versions, download the .deb or .rpm packages from the GitHub releases page (look for releases marked as "Pre-release").

Docker

The CLI is also available as a Docker image: hookdeck/hookdeck-cli.

docker run --rm -it hookdeck/hookdeck-cli version
hookdeck version x.y.z (beta)

To use a specific version (including beta releases), specify the version tag:

docker run --rm -it hookdeck/hookdeck-cli:v1.2.3-beta.1 version

Note: Beta releases do not update the latest tag. Only stable releases update latest.

If you want to login to your Hookdeck account with the CLI and persist credentials, you can bind mount the ~/.config/hookdeck directory:

docker run --rm -it -v $HOME/.config/hookdeck:/root/.config/hookdeck hookdeck/hookdeck-cli login

Then you can listen on any of your sources. Don't forget to use host.docker.internal to reach a port on your host machine, otherwise that port will not be accessible from localhost inside the container.

docker run --rm -it -v $HOME/.config/hookdeck:/root/.config/hookdeck hookdeck/hookdeck-cli listen http://host.docker.internal:1234

Usage

Installing the CLI provides access to the hookdeck command.

hookdeck [command]

# Run `--help` for detailed information about CLI commands
hookdeck [command] help

Commands

Login

Login with your Hookdeck account. This will typically open a browser window for authentication.

hookdeck login

If you are in an environment without a browser (e.g., a TTY-only terminal), you can use the --interactive (or -i) flag to log in by pasting your API key:

hookdeck login --interactive

Login is optional, if you do not login a temporary guest account will be created for you when you run other commands.

Listen

Start a session to forward your events to an HTTP server.

hookdeck listen <port-or-URL> <source-alias?> <connection-query?> [flags]

Flags:
  --path string             Sets the path to which events are forwarded (e.g., /webhooks or /api/stripe)
  --output string           Output mode: interactive (full UI), compact (simple logs), quiet (only fatal errors) (default "interactive")
  --max-connections int     Maximum concurrent connections to local endpoint (default: 50, increase for high-volume testing)
  --filter-body string      Filter events by request body using Hookdeck filter syntax (JSON)
  --filter-headers string   Filter events by request headers using Hookdeck filter syntax (JSON)
  --filter-query string     Filter events by query parameters using Hookdeck filter syntax (JSON)
  --filter-path string      Filter events by request path using Hookdeck filter syntax (JSON)

Hookdeck works by routing events received for a given source (i.e., Shopify, Github, etc.) to its defined destination by connecting them with a connection to a destination. The CLI allows you to receive events for any given connection and forward them to your localhost at the specified port or any valid URL.

Each source is assigned an Event URL, which you can use to receive events. When starting with a fresh account, the CLI will prompt you to create your first source. Each CLI process can listen to one source at a time.

The port-or-URL param is mandatory, events will be forwarded to http://localhost:$PORT/$DESTINATION_PATH when inputing a valid port or your provided URL.

Interactive Mode

The default interactive mode uses a full-screen TUI (Terminal User Interface) with an alternative screen buffer, meaning your terminal history is preserved when you exit. The interface includes:

• Connection Header: Shows your sources, webhook URLs, and connection routing
  • Auto-collapses when the first event arrives to save space
  • Toggle with i to expand/collapse connection details
• Event List: Scrollable history of all received events (up to 1000 events)
  • Auto-scrolls to show latest events as they arrive
  • Manual navigation pauses auto-scrolling
• Status Bar: Shows event details and available keyboard shortcuts
• Event Details View: Full request/response inspection with headers and body

Interactive Keyboard Shortcuts

While in interactive mode, you can use the following keyboard shortcuts:

• ↑ / ↓ or k / j - Navigate between events (select different events)
• i - Toggle connection information (expand/collapse connection details)
• r - Retry the selected event
• o - Open the selected event in the Hookdeck dashboard
• d - Show detailed request/response information for the selected event (press d or ESC to close)
  • When details view is open: ↑ / ↓ scroll through content, PgUp / PgDown for page navigation
• q - Quit the application (terminal state is restored)
• Ctrl+C - Also quits the application

The selected event is indicated by a > character at the beginning of the line. All actions (retry, open, details) work on the currently selected event, not just the latest one. These shortcuts are displayed in the status bar at the bottom of the screen.

Listen to all your connections for a given source

The second param, source-alias is used to select a specific source to listen on. By default, the CLI will start listening on all eligible connections for that source.

$ hookdeck listen 3000 shopify

●── HOOKDECK CLI ──●

Listening on 1 source • 2 connections • [i] Collapse

Shopify Source
│  Requests to → https://events.hookdeck.com/e/src_DAjaFWyyZXs