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
Manage connections (sources, destinations, and rules) directly from the CLI

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:
```
  npm install hookdeck-cli -g
  
  
```
```
  yarn global add hookdeck-cli
  
  
```
```
    brew install hookdeck/hookdeck/hookdeck
    
    
```
1. scoop bucket add hookdeck https://github.com/hookdeck/scoop-hookdeck-cli.git
2. scoop install hookdeck
1. Download the latest release's tar.gz file.
2. tar -xvf hookdeck_X.X.X_linux_x86_64.tar.gz
3. ./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 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.
- [--output] optionally controls output verbosity: interactive (default with keyboard shortcuts), compact (simple logs), or quiet (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

$ 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. 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 or domain 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:

↑ / ↓ or k / j - Navigate between events (select different events)
i - Toggle connection header (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 or Ctrl+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.

# Interactive mode (default)
$ hookdeck listen 3000 shopify

●── HOOKDECK CLI ──●

Listening on 1 source • 1 connection • [i] Collapse

shopify
│  Requests to → https://events.hookdeck.com/e/src_xxx
└─ Forwards to → http://localhost:3000 (shopify-cli)

💡 View 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 (23ms) → https://dashboard.hookdeck.com/events/evt_...

───────────────────────────────────────────────────────────────────────────────
> ✓ Last event succeeded with status 200 | [r] Retry • [o] Open in dashboard • [d] Show data

# With custom path
$ hookdeck listen 3000 shopify --path /events/shopify/orders

●── HOOKDECK CLI ──●

Listening on 1 source • 1 connection • [i] Collapse

shopify
│  Requests to → https://events.hookdeck.com/e/src_xxx
└─ Forwards to → http://localhost:3000/events/shopify/orders (shopify-cli)

💡 View 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/events/shopify/orders (19ms) → https://dashboard.hookdeck.com/events/evt_...

───────────────────────────────────────────────────────────────────────────────
> ✓ Last event succeeded with status 200 | [r] Retry • [o] Open in dashboard • [d] Show data

# Compact mode - simple logs
$ hookdeck listen 3000 shopify --output compact

Listening on

shopify
│  Requests to → https://events.hookdeck.com/e/src_xxx
└─ Forwards to → http://localhost:3000 (shopify-cli)

💡 View dashboard to inspect, retry & bookmark events: https://dashboard.hookdeck.com/events/cli

Connected. Waiting for events...

2025-10-08 15:56:53 [200] POST http://localhost:3000 (45ms) → https://...
2025-10-08 15:56:54 [422] POST http://localhost:3000 (12ms) → https://...

# Quiet mode - only fatal errors
$ hookdeck listen 3000 shopify --output quiet

Listening on

shopify
│  Requests to → https://events.hookdeck.com/e/src_xxx
└─ Forwards to → http://localhost:3000 (shopify-cli)

💡 View dashboard to inspect, retry & bookmark events: https://dashboard.hookdeck.com/events/cli

Connected. Waiting for events...

2025-10-08 15:56:53 [ERROR] Failed to POST: connection refused

# Filter with multiple conditions
$ hookdeck listen 3000 stripe --filter-body '{"type": "charge.succeeded"}' --filter-headers '{"x-stripe-signature": {"$exist": true}}'

Listening on 1 source • 1 connection • [i] Collapse

stripe
│  Requests to → https://events.hookdeck.com/e/src_xxx
└─ Forwards to → http://localhost:3000 (stripe-cli)

⏺ Filters provided, only events matching the filter will be forwarded for this session
  • Body: {"type": "charge.succeeded"}
  • Headers: {"x-stripe-signature": {"$exist": true}}

Connected. Waiting for events...

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

●── HOOKDECK CLI ──●

Listening on 1 source • 1 connection • [i] Collapse

Shopify Source
│  Requests to → https://events.hookdeck.com/e/src_DAjaFWyyZXsFdZrTOKpuHnOH
└─ Forwards to → http://localhost:3000/webhooks/shopify/orders (Orders Service)

💡 View dashboard to inspect, retry & bookmark events: https://dashboard.hookdeck.com/events/cli?team_id=...

Events • [↑↓] Navigate ──────────────────────────────────────────────────────────

> 2025-10-12 14:42:55 [200] POST http://localhost:3000/webhooks/shopify/orders (34ms) → https://dashboard.hookdeck.com/events/evt_...

───────────────────────────────────────────────────────────────────────────────
> ✓ Last event succeeded with status 200 | [r] Retry • [o] Open in dashboard • [d] Show data

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

Connection

Manage connections between sources and destinations. A connection links a source to a destination and defines how webhooks are routed. You can create connections with inline source and destination creation, or reference existing resources.

[BETA] This feature is in beta. Please share bugs and feedback via the Hookdeck CLI GitHub issues.

# Connection commands overview
$ hookdeck connection --help

Available Commands:
  create      Create a new connection
  delete      Delete a connection
  disable     Disable a connection
  enable      Enable a connection
  get         Get connection details
  list        List connections
  pause       Pause a connection temporarily
  unpause     Resume a paused connection
  upsert      Create or update a connection by name

Connection Create

hookdeck connection create [flags]

Create a connection between a source and destination. You can either reference existing resources by ID or create them inline.

Key Flags:

Flag	Description
`--name`	Required. Connection name
`--source-id`	Use existing source by ID
`--source-name`	Source name for inline creation
`--source-type`	Source type (WEBHOOK, STRIPE, etc.)
`--destination-id`	Use existing destination by ID
`--destination-name`	Destination name for inline creation
`--destination-type`	Destination type (CLI, HTTP, MOCK)
`--destination-url`	URL for HTTP destinations
`--destination-auth-method`	Auth method (bearer, basic, api_key, etc.)
`--destination-rate-limit`	Rate limit (requests per period)
`--destination-rate-limit-period`	Period (second, minute, hour, concurrent)
`--rules`	JSON string representing rules array
`--rules-file`	Path to JSON file containing rules
`--output`	Output format (json)

For complete list including authentication, source configuration, and rule options, see hookdeck connection create --help.

# Create with inline source and destination
$ hookdeck connection create \
  --name "test-webhooks-to-local" \
  --source-type WEBHOOK --source-name "test-webhooks" \
  --destination-type CLI --destination-name "local-dev"

# Output:
Connection created successfully
Connection ID: web_6DgtZkGBMQwp
Source ID: src_lw9n67ud1msd0e
Source URL: https://hkdk.events/lw9n67ud1msd0e
Destination ID: des_jNNyjGZHCTX2

# Create with existing resources
$ hookdeck connection create \
  --name "github-to-api" \
  --source-id src_abc123 \
  --destination-id dst_def456

# Create with source configuration options
$ hookdeck connection create \
  --name "api-webhooks" \
  --source-type WEBHOOK --source-name "api-source" \
  --source-allowed-http-methods "POST,PUT,PATCH" \
  --source-custom-response-content-type "json" \
  --source-custom-response-body '{"status":"received"}' \
  --destination-type CLI --destination-name "local-dev"

Connection Upsert

hookdeck connection upsert <name> [flags]

Create or update a connection using name as the unique identifier. This command is idempotent and recommended for CI/CD workflows.

When the connection doesn't exist:

Creates a new connection with the provided properties
Requires source and destination to be specified

When the connection exists:

Updates only properties that are explicitly provided
Preserves existing properties that aren't specified

Use --dry-run to preview changes before applying them.

Key Flags:

Flag	Description
`--source-id` / `--source-name` / `--source-type`	Source configuration
`--destination-id` / `--destination-name` / `--destination-type` / `--destination-url`	Destination configuration
`--destination-rate-limit` / `--destination-rate-limit-period`	Rate limiting
`--rules` / `--rules-file`	Connection rules
`--dry-run`	Preview changes without applying
`--output`	Output format (json)

See hookdeck connection upsert --help for the complete list of flags.

# Create or update with inline source and destination
$ hookdeck connection upsert "my-connection" \
  --source-name "stripe-prod" --source-type STRIPE \
  --destination-name "my-api" --destination-type HTTP \
  --destination-url https://api.example.com

# Update just the rate limit on existing connection
$ hookdeck connection upsert my-connection \
  --destination-rate-limit 100 \
  --destination-rate-limit-period minute

# Output:
Upserting connection 'my-connection'...
✔ Connection updated successfully

Connection:  my-connection (web_6DgtZkGBMQwp)
Source:      stripe-prod (src_lw9n67ud1msd0e)
Source Type: STRIPE
Source URL:  https://hkdk.events/lw9n67ud1msd0e
Destination: my-api (des_jNNyjGZHCTX2)
Destination Type: HTTP
Destination Path: /

# Update source configuration options
$ hookdeck connection upsert my-connection \
  --source-allowed-http-methods "POST,PUT,DELETE" \
  --source-custom-response-content-type "json" \
  --source-custom-response-body '{"status":"received"}'

# Preview changes with dry-run
$ hookdeck connection upsert my-connection \
  --destination-rate-limit 200 \
  --destination-rate-limit-period hour \
  --dry-run

# Output:
=== DRY RUN MODE ===

Operation: UPDATE
Connection: my-connection (ID: web_6DgtZkGBMQwp)

Changes to be applied:
  • Source: src_lw9n67ud1msd0e → src_lw9n67ud1msd0e (by ID)
  • Destination: my-api → my-api (inline creation)

Properties preserved (not specified in command):

=== DRY RUN COMPLETE ===
No changes were made. Remove --dry-run to apply these changes.

Connection List

hookdeck connection list [flags]

List all connections or filter by source, destination, or state.

Flag	Description
`--name`	Filter by connection name
`--source-id`	Filter by source ID
`--destination-id`	Filter by destination ID
`--disabled`	Include disabled connections
`--limit`	Limit number of results (default 100)
`--output`	Output format (json)

# List all connections
$ hookdeck connection list

# Output:
Found 1 connection(s):

cli-test-connection
  ID: web_6DgtZkGBMQwp
  Source: cli-test-source (src_lw9n67ud1msd0e)
  Destination: cli-test-dest (des_jNNyjGZHCTX2)
  Status: active

# Filter by connection name
$ hookdeck connection list --name my-connection

# Filter by source ID
$ hookdeck connection list --source-id src_abc123

# Filter by destination ID
$ hookdeck connection list --destination-id dst_def456

# Include disabled connections
$ hookdeck connection list --disabled

# Note: This flag shows ALL connections (both active and disabled),
# not just disabled connections

# Limit results
$ hookdeck connection list --limit 10

# Get JSON output
$ hookdeck connection list --output json

# Output (example):
[
  {
    "id": "web_6DgtZkGBMQwp",
    "name": "cli-test-connection",
    "full_name": "cli-test-source -> cli-test-connection",
    "source": {
      "id": "src_lw9n67ud1msd0e",
      "name": "cli-test-source",
      "url": "https://hkdk.events/lw9n67ud1msd0e",
      "type": "WEBHOOK"
    },
    "destination": {
      "id": "des_jNNyjGZHCTX2",
      "name": "cli-test-dest",
      "type": "CLI"
    },
    "disabled_at": null,
    "paused_at": null,
    ...
  }
]

Connection Get

hookdeck connection get <connection-id> [flags]

Get detailed information about a specific connection.

Flag	Description
`--output`	Output format (json)

# Get connection details
$ hookdeck connection get conn_abc123

# Output (text format):
Connection ID: web_6DgtZkGBMQwp
Name: cli-test-connection
Source: cli-test-source (src_lw9n67ud1msd0e)
Destination: cli-test-dest (des_jNNyjGZHCTX2)
Status: active

# Get connection with JSON output
$ hookdeck connection get conn_abc123 --output json

# Output includes complete connection details with source and destination config

Connection Delete

hookdeck connection delete <connection-id> [flags]

Delete a connection permanently. Note: The delete command help output was unavailable, but the command supports a --force flag based on similar CLI patterns.

# Delete a connection (with confirmation)
$ hookdeck connection delete conn_abc123

# Output:
Are you sure you want to delete connection 'my-connection' (conn_abc123)? [y/N]: y

✓ Connection 'my-connection' (conn_abc123) deleted successfully

# Force delete without confirmation
$ hookdeck connection delete conn_abc123 --force

# Output:
✓ Connection 'my-connection' (conn_abc123) deleted successfully

Connection Disable

hookdeck connection disable <connection-id>

Disable a connection. Disabled connections stop processing events entirely until re-enabled. This replaces the previous archive functionality.

# Disable a connection
$ hookdeck connection disable conn_abc123

# Output:
✓ Connection disabled: my-connection (conn_abc123)

Connection Enable

hookdeck connection enable <connection-id>

Enable a disabled connection. The connection will resume processing events. This replaces the previous unarchive functionality.

# Enable a connection
$ hookdeck connection enable conn_abc123

# Output:
✓ Connection enabled: my-connection (conn_abc123)

Connection Pause

hookdeck connection pause <connection-id>

Pause a connection temporarily. The connection will queue incoming events until unpaused.

Important: Paused connections queue events for later delivery. When unpaused, queued events will be processed. This is useful during maintenance windows or deployments. To stop processing completely, use disable.

# Pause a connection
$ hookdeck connection pause conn_abc123

# Output:
✓ Connection paused: my-connection (conn_abc123)
# Note: Events will be queued until the connection is unpaused

# Pause during deployment workflow
$ hookdeck connection pause conn_abc123

# Deploy your application
$ ./deploy.sh

# Resume processing
$ hookdeck connection unpause conn_abc123

Connection Unpause

hookdeck connection unpause <connection-id>

Resume a paused connection. The connection will start processing queued events.

# Unpause a connection
$ hookdeck connection unpause conn_abc123

# Output:
✓ Connection unpaused: my-connection (conn_abc123)

The Hookdeck CLI

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

Interactive Mode

Interactive Keyboard Shortcuts

Listen Flags

Filter Flags

Version

Whoami

Completion

CI

Project

List

Use

Connection

Connection Create

Connection Upsert

Connection List

Connection Get

Connection Delete

Connection Disable

Connection Enable

Connection Pause

Connection Unpause