CLI Reference - Hookdeck

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

The Hookdeck CLI can be used with the Hookdeck Console for free and with not account required. It can also be used with the Hookdeck Event Gateway and supports managing 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

Install the CLI.
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?> [cli-path?], 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.
- [--path] optionally specifies the path ($DESTINATION_PATH) events will be forwarded to.

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

$ npm install hookdeck-cli -g

$ yarn global add hookdeck-cli

macOS

Install Hookdeck CLI on macOS using Homebrew

$ brew install hookdeck/hookdeck/hookdeck

Windows

Install Hookdeck CLI on Windows using the Scoop package manager

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

Linux

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

# Unzip the file:
$ tar -xvf hookdeck_X.X.X_linux_x86_64.tar.gz
# Run the executable:
$ ./hookdeck

Docker

Install Hookdeck CLI on Docker by pulling the hookdeck/hookdeck-cli image:

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

Global Flags

Hookdeck CLI supports a number of global flags that can be appended to any command.

$ hookdeck {command} <arguments> [flags]

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

--color <setting>

Config

Set the file path for the CLI's configuration file.

Default path: $HOME/.config/hookdeck/config.toml

--config <config_filepath>

Device Name

Run the command on behalf of another device.

--device-name <name>

Help

Get documentation for a given command, including any supported flags and arguments.

-h
--help

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

--log-level <level>

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

-p <name>
--project-name <name>

Version

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

-v
--version

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 login

Press Enter to open the browser (^C to quit)

Logout

hookdeck logout [flags]

Clear your credentials.

$ hookdeck logout

Logging out...
Credentials have been cleared for the default project.

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. 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.

Listen Flags

--path

An optional flag that allows you to specify localhost path ($DESTINATION_PATH) events will be forwarded to.

$ hookdeck listen 3000 shopify

Dashboard
👉 Inspect and replay webhooks: https://dashboard.hookdeck.io/cli/events

Shopify Source
🔌 Webhook URL: https://events.hookdeck.com/e/src_xxx

Connections
Orders forwarding to /webhooks/shopify/orders

⣾ Getting ready...

$ hookdeck listen 3000 shopify --path /events/shopify/orders

Dashboard
👉 Inspect and replay webhooks: https://dashboard.hookdeck.io/cli/events

Shopify Source
🔌 Webhook URL: https://events.hookdeck.com/e/src_xxx

Connections
Orders forwarding to /events/shopify/orders

⣾ Getting ready...

Version

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

$ hookdeck version

Whoami

Print your current username and project, if logged in.

$ hookdeck whoami

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.

$ hookdeck completion

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.

$ hookdeck ci --api-key $HOOKDECK_API_KEY
Done! The Hookdeck CLI is configured in project MyProject

$ hookdeck listen 3000 shopify orders

👉  Inspect and replay webhooks: https://dashboard.hookdeck.com/cli/events

Shopify Source
🔌 Webhook URL: https://events.hookdeck.com/e/src_DAjaFWyyZXsFdZrTOKpuHnOH

Connections
Inventory Service forwarding to /webhooks/shopify/inventory


⣾ Getting ready...

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.

$ hookdeck project list
My Project (current)
Another Project
Yet Another One

$ hookdeck project use
Use the arrow keys to navigate: ↓ ↑ → ←
? Select Project:
    My Project
    Another Project
  ▸ Yet Another One

Selecting project Yet Another One

$ hookdeck whoami
Using profile default
Logged in as Me in project Yet Another One

List

hookdeck project list

$ hookdeck project list
My Project (current)
Another Project
Yet Another One

Use

hookdeck project use [flags]

Flags	Type	Description
local	`boolean`	Optional. Pin active project to the current directory

$ hookdeck project use
Use the arrow keys to navigate: ↓ ↑ → ←
? Select Project:
    My Project
    Another Project
  ▸ Yet Another One

Selecting project Yet Another One

# Or use this command to pin the project to the current directory

$ hookdeck project use --local
Use the arrow keys to navigate: ↓ ↑ → ←
? Select Project:
    My Project
    Another Project
  ▸ Yet Another One

Pinning project Yet Another One to current directory

Why use the CLI

Getting started with the CLI

Installation

NPM & Yarn

macOS

Windows

Linux

Docker

Global Flags

Color

Config

Device Name

Help

Log Level

Project Name

Version

Login

Logout

Logout Flags

Listen

Listen Flags

Version

Whoami

Completion

CI

Project

List

Use