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>] [flags]

Flags:

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]

Arguments:

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]

Arguments:

Flags:

Note: connection upsert --dry-run output

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

$ hookdeck gateway 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]

Arguments:

Flags:

hookdeck gateway connection enable

Enable a disabled connection.

Usage:

hookdeck gateway connection enable <connection-id>

Arguments:

hookdeck gateway connection disable

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

Usage:

hookdeck gateway connection disable <connection-id>

Arguments:

hookdeck gateway connection pause

Pause a connection temporarily.

The connection will queue incoming events until unpaused.

Usage:

hookdeck gateway connection pause <connection-id>

Arguments:

hookdeck gateway connection unpause

Resume a paused connection.

The connection will start processing queued events.

Usage:

hookdeck gateway connection unpause <connection-id>

Arguments:

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:

Issue

Manage Hookdeck issues.

Issues are automatically created when delivery failures, transformation errors, or backpressure conditions are detected. Use these commands to list, inspect, update the status of, or dismiss issues.

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

Usage:

hookdeck gateway issue [command]

Global options:

hookdeck gateway issue list

List issues or filter by type and status.

Usage:

hookdeck gateway issue list [flags]

Flags:

hookdeck gateway issue get

Get detailed information about a specific issue.

Usage:

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

Flags:

hookdeck gateway issue update

Update an existing issue by its ID.

The --status flag is required. Valid statuses: OPENED, IGNORED, ACKNOWLEDGED, RESOLVED.

Usage:

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

Flags:

hookdeck gateway issue dismiss

Dismiss an issue. This sends a DELETE request to the API.

Usage:

hookdeck gateway issue dismiss <issue-id> [flags]

Flags:

hookdeck gateway issue count

Count issues matching optional filters.

Usage:

hookdeck gateway issue count [flags]

Flags:

Metrics

Query metrics for events, requests, attempts, and transformations. Requires --start and --end (ISO 8601 date-time). Use subcommands to choose the metric type.

For event metrics you can query volume, queue depth, pending over time, or per-issue; use --measures, --dimensions, and --issue-id on the events subcommand.

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

Usage:

hookdeck gateway metrics [command]

Global options:

hookdeck gateway metrics events

Query event metrics: volume and success/failure counts, error rate, queue depth, pending over time, or per-issue. Use --measures and --dimensions to choose what to query. Requires --start and --end.

When querying per-issue (e.g. --dimensions issue_id), --issue-id is required.

Measures: count, successful_count, failed_count, scheduled_count, paused_count, error_rate, avg_attempts, scheduled_retry_count, pending, queue_depth, max_depth, max_age. Dimensions: connection_id, source_id, destination_id, issue_id.

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

Usage:

hookdeck gateway metrics events [flags]

Flags:

hookdeck gateway metrics requests

Query metrics for requests (acceptance, rejection, etc.). Measures: count, accepted_count, rejected_count, discarded_count, avg_events_per_request, avg_ignored_per_request.

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

Usage:

hookdeck gateway metrics requests [flags]

Flags:

hookdeck gateway metrics attempts

Query metrics for delivery attempts (latency, success/failure). Measures: count, successful_count, failed_count, delivered_count, error_rate, response_latency_avg, response_latency_max, response_latency_p95, response_latency_p99, delivery_latency_avg.

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

Usage:

hookdeck gateway metrics attempts [flags]

Flags:

hookdeck gateway metrics transformations

Query metrics for transformations. Measures: count, successful_count, failed_count, error_rate, error_count, warn_count, info_count, debug_count.

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

Usage:

hookdeck gateway metrics transformations [flags]

Flags:

Use cases

Substitute your own date range for --start and --end in the examples below.

Event volume and failure rate over time

Query event volume, success/failure counts, and error rate over time.

hookdeck gateway metrics events \
  --start 2026-02-01T00:00:00Z --end 2026-02-25T00:00:00Z \
  --granularity 1d \
  --measures count,failed_count,error_rate

Request acceptance vs rejection

See how many requests were accepted versus rejected by your connections.

hookdeck gateway metrics requests \
  --start 2026-02-01T00:00:00Z --end 2026-02-25T00:00:00Z \
  --measures count,accepted_count,rejected_count

Delivery latency (attempts)

Measure delivery latency and success/failure for attempts to your destinations.

hookdeck gateway metrics attempts \
  --start 2026-02-01T00:00:00Z --end 2026-02-25T00:00:00Z \
  --measures response_latency_avg,response_latency_p95

Queue backlog per destination

Inspect queue depth (max_depth, max_age) per destination to spot backpressure. Use the events subcommand with queue-depth measures; the CLI routes to the queue-depth API.

hookdeck gateway metrics events \
  --start 2026-02-01T00:00:00Z --end 2026-02-25T00:00:00Z \
  --measures max_depth,max_age \
  --destination-id dest_xxx

Pending events over time

View pending events as a timeseries to see how the queue drains over time. Use events with the pending measure and --granularity; the CLI routes to the pending-timeseries API.

hookdeck gateway metrics events \
  --start 2026-02-01T00:00:00Z --end 2026-02-25T00:00:00Z \
  --granularity 1h \
  --measures pending

Events grouped by issue (debugging)

Group events by issue for debugging. Use events with --dimensions issue_id and --issue-id (issue ID from the Dashboard).

hookdeck gateway metrics events \
  --start 2026-02-01T00:00:00Z --end 2026-02-25T00:00:00Z \
  --dimensions issue_id \
  --issue-id iss_xxx \
  --measures count

Events grouped by connection or destination

Break down event volume by connection or destination using --dimensions.

hookdeck gateway metrics events \
  --start 2026-02-01T00:00:00Z --end 2026-02-25T00:00:00Z \
  --granularity 1d \
  --dimensions connection_id \
  --measures count,successful_count,failed_count

Scheduled and paused event counts

See how many events are scheduled for retry or paused (e.g. connection paused).

hookdeck gateway metrics events \
  --start 2026-02-01T00:00:00Z --end 2026-02-25T00:00:00Z \
  --granularity 1d \
  --measures scheduled_count,paused_count

Request fan-out (events per request)

See average events produced per request (e.g. one webhook fan-out to multiple connections).

hookdeck gateway metrics requests \
  --start 2026-02-01T00:00:00Z --end 2026-02-25T00:00:00Z \
  --measures count,avg_events_per_request

Transformation errors and log levels

Track transformation runs, error rate, and log-level counts (error, warn, info, debug).

hookdeck gateway metrics transformations \
  --start 2026-02-01T00:00:00Z --end 2026-02-25T00:00:00Z \
  --measures count,failed_count,error_rate,error_count,warn_count

Mcp

Starts a Model Context Protocol (MCP) server over stdio.

The server exposes Hookdeck Event Gateway resources — connections, sources, destinations, events, requests, and more — as MCP tools that AI agents and LLM-based clients can invoke.

If the CLI is already authenticated, all tools are available immediately. If not, a hookdeck_login tool is provided that initiates browser-based authentication so the user can log in without leaving the MCP session.

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

Usage:

hookdeck gateway mcp

Global options:

Prerequisites: install the CLI

The MCP server runs inside the Hookdeck CLI. You must install the CLI before you can use the MCP. The MCP client (e.g. Cursor, Claude Code) will start the server by running the hookdeck binary.

Install the CLI using one of the methods in Installation: Homebrew (brew install hookdeck/hookdeck/hookdeck), npm/yarn (npm install hookdeck-cli -g), Scoop on Windows, or a direct binary from the releases page. Ensure hookdeck is on your PATH so your MCP client can invoke it.

What is MCP?

Model Context Protocol (MCP) is an open protocol that lets AI agents and LLM-based clients connect to tools and data sources. The Hookdeck CLI runs an MCP server that exposes your Event Gateway resources — connections, sources, destinations, events, requests, attempts, issues, and metrics — as MCP tools.

Use hookdeck gateway mcp when you want an AI assistant (e.g. in an IDE or chat) to query and inspect Hookdeck without leaving the session. For creating or changing resources (sources, connections, retries, etc.), use the Hookdeck Agent Skills so the agent can run CLI commands or call the API (see When to use MCP vs Agent Skills below).

How the client connects to the server

The Hookdeck MCP uses stdio transport only: the server reads JSON-RPC from stdin and writes responses to stdout. There is no network port or URL to connect to.

The MCP client starts its own server process. You do not run hookdeck gateway mcp in a terminal and then point the client at it. Instead, you configure the client with the command and args to run; when the client needs the Hookdeck tools, it spawns that process and talks to it over stdin/stdout. When the client session ends, that process exits. Other transports (e.g. SSE or HTTP, where you connect to an already-running server) are not supported by the Hookdeck CLI.

Authentication

If the CLI is already authenticated (e.g. you have run hookdeck login or set HOOKDECK_API_KEY), all tools are available immediately. If not, the server registers a hookdeck_login tool that starts browser-based authentication so you can log in without leaving the MCP session.

Configuring the MCP

Command and arguments

Configure your MCP client with the CLI as the server process:

• Command: hookdeck (or the full path to the binary if it is not on your PATH)
• Args: ["gateway", "mcp"]

No other arguments are required. The client spawns this process when it needs Hookdeck tools and communicates over stdio.

Example: Cursor

In Cursor, add the server under mcpServers in your MCP settings (e.g. in .cursor/mcp.json or Cursor Settings → MCP). Use the name hookdeck-gateway (or any label you prefer):

{
  "mcpServers": {
    "hookdeck-gateway": {
      "command": "hookdeck",
      "args": ["gateway", "mcp"],
      "env": {}
    }
  }
}

To use a specific config file or profile, add flags to args or set environment variables in env:

{
  "mcpServers": {
    "hookdeck-gateway": {
      "command": "hookdeck",
      "args": ["--hookdeck-config", "/path/to/config.toml", "gateway", "mcp"],
      "env": {}
    }
  }
}

With environment variables (e.g. for a project-specific config or API key):

{
  "mcpServers": {
    "hookdeck-gateway": {
      "command": "hookdeck",
      "args": ["gateway", "mcp"],
      "env": {
        "HOOKDECK_CONFIG_FILE": "/path/to/project/.hookdeck/config.toml"
      }
    }
  }
}

Other MCP clients (e.g. Claude Code, Windsurf) use a similar pattern: you specify a command and args (and optionally env); the client starts that process and uses stdio. There is no URL or port to configure for the Hookdeck MCP.

Useful options

• Config file — --hookdeck-config /path/to/config.toml in args, or HOOKDECK_CONFIG_FILE in env.
• Profile — Add -p, my-profile (or --profile, my-profile) to args.
• API key — Set HOOKDECK_API_KEY in env for headless or CI-like use so the MCP does not require interactive login.
• Log level — Add --log-level, debug to args when debugging the MCP or CLI.

Debugging and logging

The MCP server uses the same logging as the rest of the CLI. Logs are written to stderr so they do not interfere with the JSON-RPC protocol on stdout.

• Control verbosity — Pass --log-level to the command: debug, info (default), warn, or error. For example, add "--log-level" and "debug" to args in your MCP config to see detailed tool and login flow messages.
• Where to see logs — The client spawns the server process, so stderr is handled by the client. Check your client’s documentation for where it shows or stores server stderr (e.g. an “MCP server log”, “Extension host” log, or developer console). To capture stderr yourself for one-off debugging, you can run hookdeck --log-level debug gateway mcp in a terminal and pipe JSON-RPC into it; in normal use the client starts its own process, so look for the client’s log location for the Hookdeck server’s stderr.

Available tools

The MCP server exposes the following tools. Use hookdeck_help (with no topic, or with topic: "hookdeck_events" etc.) from the agent to get an overview or detailed parameter help.

When the CLI is not yet authenticated, hookdeck_login is also available so the agent can prompt you to log in via the browser.

Example prompts

Once the MCP is connected, you can ask your agent questions in natural language. The agent will call the appropriate tools. For example:

• "Are any of my events failing right now?"
  → Agent uses hookdeck_issues to list open issues, then hookdeck_events to inspect recent failures.

• "Show me the last 10 events for my Stripe source and check if any failed."
  → Agent uses hookdeck_sources to find the Stripe source, then hookdeck_events filtered by source and status.

• "What's the error rate for my API destination over the last 24 hours?"
  → Agent uses hookdeck_metrics with measures like failed_count and count, grouped by destination.

• "Trace request req_abc123 — what events did it produce, and did they all deliver successfully?"
  → Agent uses hookdeck_requests to get the request, then the events action to list generated events.

• "Why is my checkout endpoint returning 500s? Show me the latest attempt details."
  → Agent uses hookdeck_events filtered by status FAILED, then hookdeck_attempts to inspect delivery details.

• "Pause the connection between Stripe and my staging endpoint while I debug."
  → Agent uses hookdeck_connections to find and pause the connection.

• "Compare failure rates across all my destinations this week."
  → Agent uses hookdeck_metrics with dimensions set to destination_id and measures like error_rate.

FAQ — What you can and can't do with the Hookdeck MCP

What the Hookdeck MCP can do

• Query and inspect — List and get connections, sources, destinations, transformations, requests, events, attempts, and issues. Fetch request/event payloads (raw body) and filter by status, source, destination, time range, etc.
• Metrics — Run aggregate metrics queries over a time range (counts, success/failure rates, queue depth, etc.).
• Control flow — Pause and unpause connections; switch the active project for the session.
• Authentication — Use the hookdeck_login tool when not yet authenticated to complete browser-based login.

What the Hookdeck MCP cannot do

• Create or update resources — The MCP does not expose tools to create or update sources, destinations, connections, or transformations. It also cannot create or edit transformations or connection rules.
• Retry events — Retrying a failed event is not available via the MCP; use the Dashboard or the CLI/API (e.g. hookdeck gateway event retry <id>).
• Delete resources — Deletion of connections, sources, destinations, or other resources is not exposed in the MCP.

For write operations and full resource management (create connection, create source, retry event, etc.), use the Hookdeck Agent Skills. The skills guide the agent to invoke the Hookdeck CLI or the Hookdeck API, so you get both discovery (MCP for querying) and execution (skills for changes).

When to use MCP vs Agent Skills

Install the skills with:

npx skills add hookdeck/agent-skills --skill event-gateway

The agent can then follow the skill’s workflow to set up connections, run hookdeck listen, use the API for dynamic resource creation, and perform retries or other write operations. Use the MCP for read-only inspection and metrics from inside your IDE or chat; use the skills when the agent needs to modify your Hookdeck project.