The Hookdeck CLI
The Hookdeck CLI supports the following functionality:
- Forward webhook events to a local web server
- Quickly replay and inspect data of events forwarded to your local web server
- Use in combination with the Hookdeck Console as a free alternative to ngrok
- Use with the Hookdeck Event Gateway to support your local development workflows and to manage Hookdeck projects in CI/CD for testing
Why use the CLI
With the CLI, you can develop, test, and troubleshoot your integration with Hookdeck – all without interfering with your production setup. It functions as a free replacement for ngrok and other tunnel solutions when working with event-driven application events such as webhooks.
Getting started with the CLI
npm install hookdeck-cli -g
yarn global add hookdeck-cli
brew install hookdeck/hookdeck/hookdeck
-
scoop bucket add hookdeck https://github.com/hookdeck/scoop-hookdeck-cli.git
-
scoop install hookdeck
-
Download the latest release's tar.gz file.
-
tar -xvf hookdeck_X.X.X_linux_x86_64.tar.gz
-
./hookdeck
-
Run the
hookdeck
command in your shell to ensure the CLI is installed.Optionally, log in using
hookdeck login
. Otherwise, a temporary guest account is created for you when running commands.Start a session to forward your webhooks to a local HTTP server using:
hookdeck listen <port> <source-name?> <connection-query?> [--path? /path] [--output? mode]
Where:
<port>
defines the localhost port to listen on. Webhooks will be forwarded tohttp://localhost:$PORT/$DESTINATION_PATH
.<source-name>
defines a specific source to listen on, if any. By default, the CLI will start listening on all eligible connections for that source.<connection-query>
defines which connection to listen for on the specified source. Valid inputs are the name of the connection, or the path of the associated destination.[--path]
optionally specifies the path ($DESTINATION_PATH
) events will be forwarded to.[--output]
optionally controls output verbosity:interactive
(default with keyboard shortcuts),compact
(simple logs), orquiet
(fatal errors only).
Interactive mode (default) uses a full-screen TUI with an alternative screen buffer, preserving your terminal history when you exit. The interface includes a collapsible connection header, scrollable event list (up to 1000 events), status bar with shortcuts, and detailed event inspection. You can navigate events with arrow keys, retry requests, open events in the dashboard, and view full request/response data. Use --output compact
for simple logging or --output quiet
for minimal output.
Events sent to your CLI are available on your CLI Events page, where they can be viewed, filtered, or bookmarked for future use. You can also retry CLI events to replay them locally.
Installation
Hookdeck CLI is available for macOS, Windows, Linux, and Docker.
NPM & Yarn
Install Hookdeck CLI on any platform using NPM or Yarn
macOS
Install Hookdeck CLI on macOS using Homebrew
Windows
Install Hookdeck CLI on Windows using the Scoop package manager
Linux
Install Hookdeck CLI on Linux without a package manager by downloading the latest release's tar.gz file:
Docker
Install Hookdeck CLI on Docker by pulling the hookdeck/hookdeck-cli
image:
Global Flags
Hookdeck CLI supports a number of global flags that can be appended to any command.
Color
Enable or disable color output.
Setting | Description |
---|---|
on | Enable color output |
off | Disable color output |
auto | Use the default output color based on global settings |
Config
Set the file path for the CLI's configuration file.
Default path: $HOME/.config/hookdeck/config.toml
Device Name
Run the command on behalf of another device.
Help
Get documentation for a given command, including any supported flags and arguments.
Log Level
Set the level of detail for log messages.
Default level: info
Level | Description |
---|---|
debug | Useful for development purposes |
info | Shows standard logs |
warn | Shows any warnings detected |
error | Shows everything, including errors |
Project Name
Define a project name for the CLI's current configuration. Enables multiple configurations across Hookdeck accounts, stored within one configuration file.
Any command can be run in the context of a project.
Default project: default
Version
Print the version of Hookdeck CLI. This flag should be run without any other flags or arguments set.
Login
hookdeck login [flags]
Connect the CLI to your Hookdeck account by logging in.
If you do not log in, a temporary guest account is created for you when running commands.
Logout
hookdeck logout [flags]
Clear your credentials.
Logout Flags
--all
Log out of all project-specific configurations.
Listen
hookdeck listen <port or domain> <source?> <connection-query?> [flags]
Start a session to forward your webhooks to a local HTTP server, or to an external domain.
Argument | Type | Description |
---|---|---|
port | number | Port to forward the webhooks to on your local server. The forward URL will be http://localhost:$PORT/$DESTINATION_PATH |
domain | string | Domain to forward the webhooks to from your local server. The forward URL will be http://domain/$DESTINATION_PATH |
source | string | Optional. The name of a source to listen to, a comma-separated list of source names to listen to, or '*' (with quotes) to listen to all sources. If left empty, the CLI will prompt you with a list of sources to choose from. |
connection-query | string | Optional. Used to filter the list of connections the CLI will listen to. The connection query can either be the connection name or the path . |
Only one of
port
ordomain
is required.
Interactive Mode
The default interactive mode uses a full-screen TUI (Terminal User Interface) with an alternative screen buffer, preserving your terminal history when you exit. The interface includes:
- Connection Header: Shows 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:
↑
/↓
ork
/j
- Navigate between events (select different events)i
- Toggle connection header (expand/collapse connection details)r
- Retry the selected evento
- Open the selected event in the Hookdeck dashboardd
- Show detailed request/response information for the selected event (pressd
orESC
to close)- When details view is open:
↑
/↓
scroll through content,PgUp
/PgDown
for page navigation
- When details view is open:
q
orCtrl+C
- Quit the application (terminal state is restored)
The selected event is indicated by a >
character at the beginning of the line. All actions work on the currently selected event, not just the latest one. Shortcuts are displayed in the status bar at the bottom of the screen.
Listen Flags
--path
An optional flag that allows you to specify localhost path ($DESTINATION_PATH
) events will be forwarded to.
--output
Controls how events are displayed. Useful for reducing resource usage in high-throughput scenarios or when running in the background.
interactive
(default) - Full-screen TUI with alternative screen buffer, event history, navigation, and keyboard shortcuts. Terminal history is preserved and restored when you exit.compact
- Simple one-line logs for all events without interactive features. Events are appended to your terminal history.quiet
- Only displays fatal connection errors (network failures, timeouts), not HTTP errors
All modes display connection information at startup and a connection status message.
Filter Flags
Filter flags allow you to filter events by request body, headers, query parameters, and path. Only events matching the filter will be forwarded to your local server. Filter follow Hookdeck's filter syntax. Filters only apply to the events for that specific session and is not reflected on the connection.
--filter-body
Filter events by request body.
--filter-headers
Filter events by request headers.
--filter-query
Filter events by query parameters. Query parameters as parsed and JSON and the filter will be applied to the parsed query parameters.
--filter-path
Filter events by request path.
Version
Print your CLI version, and check whether a new version is available.
Whoami
Print your current username and project, if logged in.
Completion
Configure auto-completion for Hookdeck CLI. This command is run on install when using Homebrew or Scoop. You can optionally run this command when using the binaries directly, or without a package manager.
CI
If you want to use Hookdeck in CI for tests or any other purposes, you can use your HOOKDECK_API_KEY to authenticate and start forwarding events.
hookdeck ci [flags]
Flags | Type | Description |
---|---|---|
api-key | string | Optional. Your Hookdeck Project API key. The CLI will read automatically checks HOOKDECK_API_KEY in the environment variable. |
name | string | Optional. The name of the CI (ex: GITHUB_REF ) if you want to identify them in the dashboard later. |
Project
If you are a part of multiple projects, you can switch between them using our project management commands.
Projects were previously known as "Workspaces" in the Hookdeck dashboard. The CLI command has been updated to reflect the terminology change.
List
hookdeck project list
Use
hookdeck project use [flags]
Flags | Type | Description |
---|---|---|
local | boolean | Optional. Pin active project to the current directory |