The Hookdeck CLI lets you forward events received on any Hookdeck connection to a local web server and manage your Hookdeck projects.

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

  1. Install the CLI.

  2. Run the hookdeck command in your shell to ensure the CLI is installed.

  3. Optionally, log in using hookdeck login. Otherwise, a temporary guest account is created for you when running commands.

  4. Start a session to forward your webhooks to a local HTTP server using hookdeck listen <port> <source-name?> <connection-query?>, where:

    • <port> defines the localhost port to listen on. Webhooks will be forwarded to http://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.

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.


Hookdeck CLI is available for macOS, Windows, Linux, and Docker.

NPM & Yarn

Install Hookdeck CLI on any platform using NPM or Yarn


Install Hookdeck CLI on macOS using Homebrew


Install Hookdeck CLI on Windows using the Scoop package manager


Install Hookdeck CLI on Linux without a package manager by downloading the latest release's tar.gz file:


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.


Enable or disable color output.

onEnable color output
offDisable color output
autoUse the default output color based on global settings


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.


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

debugUseful for development purposes
infoShows standard logs
warnShows any warnings detected
errorShows 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


Print the version of Hookdeck CLI. This flag should be run without any other flags or arguments set.


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.


hookdeck logout [flags]

Clear your credentials.

Logout Flags


Log out of all project-specific configurations.


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.

portnumberPort to forward the webhooks to on your local server. The forward URL will be http://localhost:$PORT/$DESTINATION_PATH
domainstringDomain to forward the webhooks to from your local server. The forward URL will be http://domain/$DESTINATION_PATH
sourcestringOptional. The name of the source to listen to. If left empty, the CLI will prompt you with a list of sources to choose from.
connection-querystringOptional. By default, all connections associated with the source will be listened on. Use this argument to filter the list of connections. Valid inputs are the name of the connection, or the path of the associated destination.

Only one of port or domain is required.


Print your CLI version, and check whether a new version is available.


Print your current username and project, if logged in.


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.


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]

api-keystringOptional. Your Hookdeck Project API key. The CLI will read automatically checks HOOKDECK_API_KEY in the environment variable.
namestringOptional. The name of the CI (ex: GITHUB_REF) if you want to identify them in the dashboard later.


If you are a part of multiple projects, you can switch between them using our project management commands.

Workspaces are now known as "Projects" in the Hookdeck dashboard. The CLI command will be updated to reflect the terminology change.


hookdeck workspace list


hookdeck workspace use [flags]

localbooleanOptional. Pin active workspace to the current directory