CLI for Hookdeck: forward webhooks to localhost (ngrok alternative), manage and query Event Gateway resources (sources, connections, destinations, events), run the MCP server for AI agents. Free for dev.
# Add to your Claude Code skills
git clone https://github.com/hookdeck/hookdeck-cli
README.md
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.
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_DAjaFWyyZXsFdZrTOKpuHnOH
├─ Forwards to → http://localhost:3000/webhooks/shopify/inventory (Inventory Service)
└─ Forwards to → http://localhost:3000/webhooks/shopify/orders (Orders Service)
💡 Open dashboard to inspect, retry & bookmark events: https://dashboard.hookdeck.com/events/cli?team_id=...
Events • [↑↓] Navigate ──────────────────────────────────────────────────────────
2025-10-12 14:32:15 [200] POST http://localhost:3000/webhooks/shopify/orders (23ms) → https://dashboard.hookdeck.com/events/evt_...
> 2025-10-12 14:32:18 [200] POST http://localhost:3000/webhooks/sh
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
A Claude Code plugin that automatically captures everything Claude does during your coding sessions, compresses it with AI (using Claude's agent-sdk), and injects relevant context back into future sessions.
