The Hookdeck CLI

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.

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

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.

Listen

Forward events for a source to your local server.

This command will create a new Hookdeck Source if it doesn't exist.

By default the Hookdeck Destination will be named "{source}-cli", and the Destination CLI path will be "/". To set the CLI path, use the "--path" flag.

Usage:

hookdeck listen [port or forwarding URL] [source] [connection] [flags]

Arguments:

Flags:

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. Filters follow Hookdeck's filter syntax. Filters only apply to the events for that specific session and are 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 are parsed as JSON and the filter will be applied to the parsed query parameters.

--filter-path

Filter events by request path.

Project

If you are part of multiple projects, switch between them using project management commands. Projects were previously known as "Workspaces" in the Hookdeck dashboard; the CLI has been updated to use the project terminology.

Usage:

hookdeck project [command]

Global options:

hookdeck project list

List and filter projects by organization and project name substrings

Usage:

hookdeck project list [<organization_substring>] [<project_substring>]

hookdeck project use

Set the active project for future commands

Usage:

hookdeck project use [<organization_name> [<project_name>]] [flags]

Flags:

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: https://github.com/hookdeck/hookdeck-cli/issues

Usage:

hookdeck gateway connection [command]

Global options:

hookdeck gateway connection list

List all connections or filter by source/destination.

Usage:

hookdeck gateway connection list [flags]

Flags:

hookdeck gateway connection get

Get detailed information about a specific connection.

You can specify either a connection ID or name.

Usage:

hookdeck gateway connection get <connection-id-or-name> [flags]

Flags:

hookdeck gateway connection create

Create a connection between a source and destination.

You can either reference existing resources by ID or create them inline.

Usage:

hookdeck gateway connection create [flags]

Flags:

hookdeck gateway connection upsert

Create a new connection or update an existing one by name (idempotent).

This command is idempotent - it can be safely run multiple times with the same arguments.

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 the connection with the provided properties
• Only updates properties that are explicitly provided
• Preserves existing properties that aren't specified

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

Usage:

hookdeck gateway connection upsert <name> [flags]

Flags:

Note: connection upsert --dry-run output

When you use --dry-run, the command prints a preview of the changes without applying them:

$ 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_xxx)

Changes to be applied:
  • Source: src_xxx → src_xxx (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.

hookdeck gateway connection delete

Delete a connection.

Usage:

hookdeck gateway connection delete <connection-id> [flags]

Flags:

hookdeck gateway connection enable

Enable a disabled connection.

Usage:

hookdeck gateway connection enable <connection-id>

hookdeck gateway connection disable

Disable an active connection. It will stop receiving new events until re-enabled.

Usage:

hookdeck gateway connection disable <connection-id>

hookdeck gateway connection pause

Pause a connection temporarily.

The connection will queue incoming events until unpaused.

Usage:

hookdeck gateway connection pause <connection-id>

hookdeck gateway connection unpause

Resume a paused connection.

The connection will start processing queued events.

Usage:

hookdeck gateway connection unpause <connection-id>

Source

Manage webhook and event sources.

Sources receive incoming webhooks and events. Create sources with a type (e.g. WEBHOOK, STRIPE) and optional authentication config, then connect them to destinations via connections.

[BETA] This feature is in beta. Please share bugs and feedback via: https://github.com/hookdeck/hookdeck-cli/issues

Usage:

hookdeck gateway source [command]

Global options:

hookdeck gateway source list

List all sources or filter by name or type.

Usage:

hookdeck gateway source list [flags]

Flags:

hookdeck gateway source create

Create a new source.

Requires --name and --type. Use --config or --config-file for authentication (e.g. webhook_secret, api_key).

Usage:

hookdeck gateway source create [flags]

Flags:

hookdeck gateway source get

Get detailed information about a specific source.

You can specify either a source ID or name.

Usage:

hookdeck gateway source get <source-id-or-name> [flags]

Flags:

hookdeck gateway source update

Update an existing source by its ID.

Usage:

hookdeck gateway source update <source-id> [flags]

Flags:

hookdeck gateway source delete

Delete a source.

Usage:

hookdeck gateway source delete <source-id> [flags]

Flags:

hookdeck gateway source upsert

Create a new source or update an existing one by name (idempotent).

Usage:

hookdeck gateway source upsert <name> [flags]

Flags:

Note: source upsert --dry-run output

When you use --dry-run, the command prints a preview of the changes without applying them:

$ hookdeck gateway source upsert my-webhook --type WEBHOOK --description "Updated" --dry-run

Output:

=== DRY RUN MODE ===

Operation: UPDATE
Source: my-webhook (ID: src_xxx)

Changes to be applied:
  • Type: WEBHOOK
  • Description: "Updated"

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

hookdeck gateway source enable

Enable a disabled source.

Usage:

hookdeck gateway source enable <source-id>

hookdeck gateway source disable

Disable an active source. It will stop receiving new events until re-enabled.

Usage:

hookdeck gateway source disable <source-id>

hookdeck gateway source count

Count sources matching optional filters.

Usage:

hookdeck gateway source count [flags]

Flags:

Destination

Manage webhook and event destinations.

Destinations define where Hookdeck forwards events. Create destinations with a type (HTTP, CLI, MOCK_API), optional URL and authentication, then connect them to sources via connections.

[BETA] This feature is in beta. Please share bugs and feedback via: https://github.com/hookdeck/hookdeck-cli/issues

Usage:

hookdeck gateway destination [command]

Global options:

hookdeck gateway destination list

List all destinations or filter by name or type.

Usage:

hookdeck gateway destination list [flags]

Flags:

hookdeck gateway destination create

Create a new destination.

Requires --name and --type. For HTTP destinations, --url is required. Use --config or --config-file for auth and rate limiting.

Usage:

hookdeck gateway destination create [flags]

Flags:

hookdeck gateway destination get

Get detailed information about a specific destination.

You can specify either a destination ID or name.

Usage:

hookdeck gateway destination get <destination-id-or-name> [flags]

Flags:

hookdeck gateway destination update

Update an existing destination by its ID.

Usage:

hookdeck gateway destination update <destination-id> [flags]

Flags:

hookdeck gateway destination delete

Delete a destination.

Usage:

hookdeck gateway destination delete <destination-id> [flags]

Flags:

hookdeck gateway destination upsert

Create a new destination or update an existing one by name (idempotent).

Usage:

hookdeck gateway destination upsert <name> [flags]

Flags:

Note: destination upsert --dry-run output

When you use --dry-run, the command prints a preview of the changes without applying them:

$ hookdeck gateway destination upsert my-api --type HTTP --url https://api.example.com --description "Updated" --dry-run

Output:

=== DRY RUN MODE ===

Operation: UPDATE
Destination: my-api (ID: dst_xxx)

Changes to be applied:
  • Type: HTTP
  • URL: https://api.example.com
  • Description: "Updated"

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

hookdeck gateway destination count

Count destinations matching optional filters.

Usage:

hookdeck gateway destination count [flags]

Flags:

hookdeck gateway destination enable

Enable a disabled destination.

Usage:

hookdeck gateway destination enable <destination-id>

hookdeck gateway destination disable

Disable an active destination. It will stop receiving new events until re-enabled.

Usage:

hookdeck gateway destination disable <destination-id>

Transformation

Manage JavaScript transformations for request/response processing.

Transformations run custom code to modify event payloads. Create with --name and --code (or --code-file), then attach to connections via rules. Use 'transformation run' to test code locally.

[BETA] This feature is in beta. Please share bugs and feedback via: https://github.com/hookdeck/hookdeck-cli/issues

Usage:

hookdeck gateway transformation [command]

Global options:

hookdeck gateway transformation list

List all transformations or filter by name or id.

Usage:

hookdeck gateway transformation list [flags]

Flags:

hookdeck gateway transformation create

Create a new transformation.

Requires --name and --code (or --code-file). Use --env for key-value environment variables.

Usage:

hookdeck gateway transformation create [flags]

Flags:

hookdeck gateway transformation get

Get detailed information about a specific transformation.

You can specify either a transformation ID or name.

Usage:

hookdeck gateway transformation get <transformation-id-or-name> [flags]

Flags:

hookdeck gateway transformation update

Update an existing transformation by its ID.

Usage:

hookdeck gateway transformation update <transformation-id-or-name> [flags]

Flags:

hookdeck gateway transformation delete

Delete a transformation.

Usage:

hookdeck gateway transformation delete <transformation-id-or-name> [flags]

Flags:

hookdeck gateway transformation upsert

Create a new transformation or update an existing one by name (idempotent).

Usage:

hookdeck gateway transformation upsert <name> [flags]

Flags:

Note: transformation upsert --dry-run output

When you use --dry-run, the command prints a preview of the changes without applying them:

$ hookdeck gateway transformation upsert my-transform --code "addHandler(\"transform\", (r, c) => { return r; });" --dry-run

Output:

=== DRY RUN MODE ===

Operation: UPDATE
Transformation: my-transform (ID: trs_xxx)

Changes to be applied:
  • Code: (modified)

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

hookdeck gateway transformation run

Test run transformation code against a sample request.

Provide either inline --code/--code-file or --id to use an existing transformation. The --request or --request-file must be JSON with at least "headers" (can be {}). Optional: body, path, query.

Usage:

hookdeck gateway transformation run [flags]

Flags:

Testing transformations locally with run

You can write your transformation JavaScript in a file and test it locally before creating the transformation or attaching it to a connection. This speeds up development: iterate on your code, run it against sample requests, and only deploy when it works.

Workflow:

1. Create a JavaScript file (e.g. transform.js) with your transformation code:

// transform.js
addHandler("transform", (request, context) => {
  request.body.enriched = true;
  request.body.timestamp = new Date().toISOString();
  return request;
});

request.body and request.headers are already objects (parsed by Hookdeck). You work with them directly—no JSON.parse or JSON.stringify needed.

2. Create a sample request file (e.g. sample.json) with the payload you want to test:

{"headers":{"content-type":"application/json"},"body":{"event":"payment.success"}}

3. Run the transformation locally with --code-file and --request-file:

$ hookdeck gateway transformation run --code-file ./transform.js --request-file ./sample.json

Output:

{
  "headers": {"content-type":"application/json"},
  "body": {"event":"payment.success","enriched":true,"timestamp":"2024-01-15T12:00:00.000Z"}
}

You can also pass the request inline with --request '{"headers":{}}'. Use --id to test an existing transformation instead of --code-file.

hookdeck gateway transformation count

Count transformations matching optional filters.

Usage:

hookdeck gateway transformation count [flags]

Flags:

hookdeck gateway transformation executions list

List executions for a transformation.

Usage:

hookdeck gateway transformation executions list <transformation-id-or-name> [flags]

Flags:

hookdeck gateway transformation executions get

Get a single execution by transformation ID and execution ID.

Usage:

hookdeck gateway transformation executions get <transformation-id-or-name> <execution-id> [flags]

Flags:

Request

List, get, and retry requests (raw inbound webhooks). View events or ignored events for a request.

[BETA] This feature is in beta. Please share bugs and feedback via: https://github.com/hookdeck/hookdeck-cli/issues

Usage:

hookdeck gateway request [command]

Global options:

For an overview of requests and the event lifecycle, see Requests and Events & Attempts.

Event lifecycle: A request is the raw inbound webhook received by a source. Each request can produce one or more events (when routed through connections) and each event has attempts (delivery tries). Use request events to see which events a request produced.

hookdeck gateway request list

List requests (raw inbound webhooks). Filter by source ID.

Usage:

hookdeck gateway request list [flags]

Flags:

hookdeck gateway request get

Get detailed information about a request by ID.

Usage:

hookdeck gateway request get <request-id> [flags]

Flags:

hookdeck gateway request retry

Retry a request by ID. By default retries on all connections. Use --connection-ids to retry only for specific connections.

Usage:

hookdeck gateway request retry <request-id> [flags]

Flags:

hookdeck gateway request events

List events (deliveries) created from a request.

Usage:

hookdeck gateway request events <request-id> [flags]

Flags:

hookdeck gateway request ignored-events

List ignored events for a request (e.g. filtered out or deduplicated).

Usage:

hookdeck gateway request ignored-events <request-id> [flags]

Flags:

hookdeck gateway request raw-body

Output the raw request body of a request by ID.

Usage:

hookdeck gateway request raw-body <request-id>

Event

List, get, retry, cancel, or mute events (processed webhook deliveries). Filter by connection ID (--connection-id), status, source, or destination.

[BETA] This feature is in beta. Please share bugs and feedback via: https://github.com/hookdeck/hookdeck-cli/issues

Usage:

hookdeck gateway event [command]

Global options:

For an overview of events and the event lifecycle, see Events & Attempts.

Event lifecycle: A request (raw inbound webhook) becomes one or more events (processed, routed deliveries) when associated with connections. Each event has one or more attempts (single delivery tries). Use request list to find raw webhooks, event list to find processed events, and attempt list --event-id to inspect delivery tries.

hookdeck gateway event list

List events (processed webhook deliveries). Filter by connection ID, source, destination, or status.

Usage:

hookdeck gateway event list [flags]

Flags:

hookdeck gateway event get

Get detailed information about an event by ID.

Usage:

hookdeck gateway event get <event-id> [flags]

Flags:

hookdeck gateway event retry

Retry delivery for an event by ID.

Usage:

hookdeck gateway event retry <event-id>

hookdeck gateway event cancel

Cancel an event by ID. Cancelled events will not be retried.

Usage:

hookdeck gateway event cancel <event-id>

hookdeck gateway event mute

Mute an event by ID. Muted events will not trigger alerts or retries.

Usage:

hookdeck gateway event mute <event-id>

hookdeck gateway event raw-body

Output the raw request body of an event by ID.

Usage:

hookdeck gateway event raw-body <event-id>

Attempt

List or get attempts (single delivery tries for an event). Use --event-id to list attempts for an event.

[BETA] This feature is in beta. Please share bugs and feedback via: https://github.com/hookdeck/hookdeck-cli/issues

Usage:

hookdeck gateway attempt [command]

Global options:

hookdeck gateway attempt list

List attempts for an event. Requires --event-id.

Usage:

hookdeck gateway attempt list [flags]

Flags:

hookdeck gateway attempt get

Get detailed information about an attempt by ID.

Usage:

hookdeck gateway attempt get <attempt-id> [flags]

Flags: