Skip to content
Back to search

hookdeck-cli

CLI for Hookdeck: forward webhooks to localhost (ngrok alternative), manage and query Event Gateway resources (sources, connections, destinations, events), run the MCP server for AI agents. Free for dev.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/hookdeck/hookdeck-cli with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/hookdeck/hookdeck-cli'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hookdeck--hookdeck-cli/badge.svg)](/listings/hookdeck--hookdeck-cli)

HTML

<a href="/listings/hookdeck--hookdeck-cli"><img src="/api/listings/hookdeck--hookdeck-cli/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Hookdeck CLI is available for macOS, Windows, and Linux for distros like Ubuntu, Debian, RedHat, and CentOS.

NPM

Hookdeck CLI is distributed as an NPM package:

npm install hookdeck-cli -g

To install a beta (pre-release) version:

npm install hookdeck-cli@beta -g

macOS

Hookdeck CLI is available on macOS via [Homebrew](https://brew.sh/) in [homebrew-core](https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/h/hookdeck.rb):

brew install hookdeck

New stable versions are picked up automatically by Homebrew's autobump after each release — `brew upgrade` will pull them in.

To install a beta (pre-release) version from our tap:

brew install hookdeck/hookdeck/hookdeck-beta

> [!NOTE] > When [`HOMEBREW_REQUIRE_TAP_TRUST`](https://docs.brew.sh/Taps) becomes the default in Homebrew 5.2.0 / 6.0.0, installing the beta formula from a third-party tap will require an explicit trust step: > ```sh > brew trust --formula hookdeck/hookdeck/hookdeck-beta > ``` > The stable `hookdeck` formula lives in homebrew-core and is not affected.

Windows

Hookdeck CLI is available on Windows via the [Scoop](https://scoop.sh/) package manager:

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

To install a beta (pre-release) version:

scoop install hookdeck-beta

Linux Or without package managers

To install the Hookdeck CLI on Linux without a package manager:

1. Download the latest linux tar.gz file from https://github.com/hookdeck/hookdeck-cli/releases/latest 2. Unzip the file: tar -xvf hookdeck_X.X.X_linux_amd64.tar.gz 3. Run the executable: ./hookdeck

For beta (pre-release) versions, download the `.deb` or `.rpm` packages from the [GitHub releases page](https://github.com/hookdeck/hookdeck-cli/releases) (look for releases marked as "Pre-release").

Docker

The CLI is also available as a Docker image: [`hookdeck/hookdeck-cli`](https://hub.docker.com/r/hookdeck/hookdeck-cli).

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

To use a specific version (including beta releases), specify the version tag:

docker run --rm -it hookdeck/hookdeck-cli:v1.2.3-beta.1 version

Note: Beta releases do not update the `latest` tag. Only stable releases update `latest`.

If you want to login to your Hookdeck account with the CLI and persist credentials, you can bind mount the `~/.config/hookdeck` directory:

docker run --rm -it -v $HOME/.config/hookdeck:/root/.config/hookdeck hookdeck/hookdeck-cli login

Then you can listen on any of your sources. Don't forget to use `host.docker.internal` to reach a port on your host machine, otherwise that port will not be accessible from `localhost` inside the container.

docker run --rm -it -v $HOME/.config/hookdeck:/root/.config/hookdeck hookdeck/hookdeck-cli listen http://host.docker.internal:1234

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,921 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Hookdeck CLI
  2. [slack-badge]: https://img.shields.io/badge/Slack-Hookdeck%20Developers-blue?logo=slack
  3. [![slack-badge]](https://join.slack.com/t/hookdeckdevelopers/shared_invite/zt-yw7hlyzp-EQuO3QvdiBlH9Tz2KZg5MQ)
  4. Using the Hookdeck CLI, you can forward your events (e.g. webhooks) to your local web server with unlimited **free** and **permanent** event URLs. Your event history is preserved between sessions and can be viewed, replayed, or used for testing by you and your teammates.
  5. Hookdeck CLI is compatible with most of Hookdeck's features, such as filtering and fan-out delivery. You can use Hookdeck CLI to develop or test your event (e.g. webhook) integration code locally.
  6. You can also manage Hookdeck Event Gateway resources—sources, destinations, connections, events, transformations—from the CLI. For AI and agent workflows, the Event Gateway MCP server (`hookdeck gateway mcp`) exposes these capabilities as tools in MCP-compatible clients (e.g. Cursor, Claude).
  7. Although it uses a different approach and philosophy, it's a replacement for ngrok and alternative HTTP tunnel solutions.
  8. Hookdeck for development is completely free, and we monetize the platform with our production offering.
  9. For a complete reference of all commands and flags, see [REFERENCE.md](REFERENCE.md).
  10. ## Table of contents
  11. - [Installation](#installation)
  12. - [NPM](#npm)
  13. - [macOS](#macos)
  14. - [Windows](#windows)
  15. - [Linux Or without package managers](#linux-or-without-package-managers)
  16. - [Docker](#docker)
  17. - [Usage](#usage)
  18. - [Commands](#commands)
  19. - [Login](#login)
  20. - [Listen](#listen)
  21. - [Logout](#logout)
  22. - [Skip SSL validation](#skip-ssl-validation)
  23. - [Disable health checks](#disable-health-checks)
  24. - [Version](#version)
  25. - [Completion](#completion)
  26. - [Running in CI](#running-in-ci)
  27. - [Event Gateway](#event-gateway)
  28. - [Event Gateway MCP](#event-gateway-mcp)
  29. - [Outpost](#outpost)
  30. - [Outpost MCP](#outpost-mcp)
  31. - [Manage connections](#manage-connections)
  32. - [Transformations](#transformations)
  33. - [Requests, events, and attempts](#requests-events-and-attempts)
  34. - [Manage active project](#manage-active-project)
  35. - [Telemetry](#telemetry)
  36. - [Configuration files](#configuration-files)
  37. - [Global Flags](#global-flags)
  38. - [Troubleshooting](#troubleshooting)
  39. - [Developing](#developing)
  40. - [Testing](#testing)
  41. - [Releasing](#releasing)
  42. - [Repository Setup](#repository-setup)
  43. - [CLI authentication keys](#cli-authentication-keys)
  44. - [License](#license)
  45. **Quick links:** [Local development (Listen)](#listen) · [Resource management (CLI)](#event-gateway) / [Manage connections](#manage-connections) · [AI / agent integration (Event Gateway MCP)](#event-gateway-mcp)
  46. https://github.com/user-attachments/assets/7a333c5b-e4cb-45bb-8570-29fafd137bd2
  47. ## Installation
  48. Hookdeck CLI is available for macOS, Windows, and Linux for distros like Ubuntu, Debian, RedHat, and CentOS.
  49. ### NPM
  50. Hookdeck CLI is distributed as an NPM package:
  51. ```sh
  52. npm install hookdeck-cli -g
  53. ```
  54. To install a beta (pre-release) version:
  55. ```sh
  56. npm install hookdeck-cli@beta -g
  57. ```
  58. ### macOS
  59. Hookdeck CLI is available on macOS via [Homebrew](https://brew.sh/) in [homebrew-core](https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/h/hookdeck.rb):
  60. ```sh
  61. brew install hookdeck
  62. ```
  63. New stable versions are picked up automatically by Homebrew's autobump after each release — `brew upgrade` will pull them in.
  64. To install a beta (pre-release) version from our tap:
  65. ```sh
  66. brew install hookdeck/hookdeck/hookdeck-beta
  67. ```
  68. > [!NOTE]
  69. > When [`HOMEBREW_REQUIRE_TAP_TRUST`](https://docs.brew.sh/Taps) becomes the default in Homebrew 5.2.0 / 6.0.0, installing the beta formula from a third-party tap will require an explicit trust step:
  70. > ```sh
  71. > brew trust --formula hookdeck/hookdeck/hookdeck-beta
  72. > ```
  73. > The stable `hookdeck` formula lives in homebrew-core and is not affected.
  74. ### Windows
  75. Hookdeck CLI is available on Windows via the [Scoop](https://scoop.sh/) package manager:
  76. ```sh
  77. scoop bucket add hookdeck https://github.com/hookdeck/scoop-hookdeck-cli.git
  78. scoop install hookdeck
  79. ```
  80. To install a beta (pre-release) version:
  81. ```sh
  82. scoop install hookdeck-beta
  83. ```
  84. ### Linux Or without package managers
  85. To install the Hookdeck CLI on Linux without a package manager:
  86. 1. Download the latest linux tar.gz file from https://github.com/hookdeck/hookdeck-cli/releases/latest
  87. 2. Unzip the file: tar -xvf hookdeck_X.X.X_linux_amd64.tar.gz
  88. 3. Run the executable: ./hookdeck
  89. For beta (pre-release) versions, download the `.deb` or `.rpm` packages from the [GitHub releases page](https://github.com/hookdeck/hookdeck-cli/releases) (look for releases marked as "Pre-release").
  90. ### Docker
  91. The CLI is also available as a Docker image: [`hookdeck/hookdeck-cli`](https://hub.docker.com/r/hookdeck/hookdeck-cli).
  92. ```sh
  93. docker run --rm -it hookdeck/hookdeck-cli version
  94. hookdeck version x.y.z (beta)
  95. ```
  96. To use a specific version (including beta releases), specify the version tag:
  97. ```sh
  98. docker run --rm -it hookdeck/hookdeck-cli:v1.2.3-beta.1 version
  99. ```
  100. Note: Beta releases do not update the `latest` tag. Only stable releases update `latest`.
  101. If you want to login to your Hookdeck account with the CLI and persist
  102. credentials, you can bind mount the `~/.config/hookdeck` directory:
  103. ```sh
  104. docker run --rm -it -v $HOME/.config/hookdeck:/root/.config/hookdeck hookdeck/hookdeck-cli login
  105. ```
  106. Then you can listen on any of your sources. Don't forget to use
  107. `host.docker.internal` to reach a port on your host machine, otherwise
  108. that port will not be accessible from `localhost` inside the container.
  109. ```sh
  110. docker run --rm -it -v $HOME/.config/hookdeck:/root/.config/hookdeck hookdeck/hookdeck-cli listen http://host.docker.internal:1234
  111. ```
  112. ## Usage
  113. Installing the CLI provides access to the `hookdeck` command.
  114. ```sh
  115. hookdeck [command]
  116. # Run `--help` for detailed information about CLI commands
  117. hookdeck [command] help
  118. ```
  119. ## Commands
  120. ### Login
  121. Login with your Hookdeck account. This will typically open a browser window for authentication.
  122. ```sh
  123. hookdeck login
  124. ```
  125. If you are in an environment without a browser (e.g., a TTY-only terminal), you can use the `--interactive` (or `-i`) flag to log in by pasting your API key:
  126. ```sh
  127. hookdeck login --interactive
  128. ```
  129. To authenticate with a **CLI client key** from the Hookdeck product (no browser step when the key is already associated with your account and project):
  130. ```sh
  131. hookdeck login --cli-key <key>
  132. ```
  133. The CLI validates the key via the API and writes your config, replacing a guest Console profile if one exists. For example, Hookdeck may show this command during Event Gateway onboarding or when authorizing the CLI as a Console destination.
  134. > Guest sandbox upgrade (keeping Console data) requires `hookdeck login` without `--cli-key`, not product copy-paste keys. If you do not log in, a temporary **guest** account is created when you run commands such as `hookdeck listen`.
  135. ### Listen
  136. Start a session to forward your events to an HTTP server.
  137. ```sh
  138. hookdeck listen <port-or-URL> <source-alias?> <connection-query?> [flags]
  139. Flags:
  140. --path string Sets the path to which events are forwarded (e.g., /webhooks or /api/stripe)
  141. --output string Output mode: interactive (full UI), compact (simple logs), quiet (only fatal errors) (default "interactive")
  142. --max-connections int Maximum concurrent connections to local endpoint (default: 50, increase for high-volume testing)
  143. --filter-body string Filter events by request body using Hookdeck filter syntax (JSON)
  144. --filter-headers string Filter events by request headers using Hookdeck filter syntax (JSON)
  145. --filter-query string Filter events by query parameters using Hookdeck filter syntax (JSON)
  146. --filter-path string Filter events by request path using Hookdeck filter syntax (JSON)
  147. --cli-key string Authenticate with a user-scoped CLI key instead of the stored login
  148. --api-key string Authenticate with a project-scoped key instead of the stored login
  149. ```
  150. By default `listen` uses the credentials saved by `hookdeck login`. To authenticate a single invocation without logging in first — for example in CI or when switching accounts — pass a key directly:
  151. ```sh
  152. # User-scoped CLI key (created by `hookdeck login`; can access all your projects)
  153. $ hookdeck listen 3000 stripe --cli-key <your-cli-key>
  154. # Project-scoped key (e.g. a Project API key or a key from `hookdeck ci`)
  155. $ hookdeck listen 3000 stripe --api-key <your-project-api-key>
  156. ```
  157. Which key you hold decides what the CLI can do. The supported ways to supply one are `hookdeck login` for a CLI key, `hookdeck login --cli-key` to paste an existing one, and `hookdeck ci --api-key` for a project API key:
  158. | Key | Where it comes from | Reach | `project list` / `project use` |
  159. | --- | --- | --- | --- |
  160. | **CLI key** | `hookdeck login`, or `hookdeck login --cli-key` | every project in every organization you belong to | yes |
  161. | **Project API key** | dashboard, or `hookdeck ci --api-key` | the one project it belongs to | no |
  162. | **Organization API key** | dashboard | its organization's projects, given the `projects.read` scope | no |
  163. Only a CLI key can list or switch projects. The others are scoped below the level that question is asked at, so `hookdeck project list` answers `this credential is scoped to a single project`, and you need `hookdeck login` for account-wide access.
  164. `hookdeck ci --api-key` takes a **project** API key specifically. It exchanges it for a project-scoped CLI key, which is why keys minted that way cannot list projects either. An organization API key is rejected by `hookdeck ci` and by every other CLI sign-in path, so it cannot be used to authenticate the CLI at all — use it against the REST API directly.
  165. See also [Credential Types](#security-config-files-and-source-control) for how each is stored.
  166. The Event Gateway routes events received for a given `source` (e.g. Shopify, GitHub) to a `destination` via a `connection`. `hookdeck listen` is a standalone command that works with whichever product you're authenticated with — Hookdeck Console or the Event Gateway — receiving events for a given connection and forwarding them to your localhost at the specified port or any valid URL.
  167. Each `source` is assigned an Event URL, which you can use to receive events. When starting with a fresh account, the CLI will prompt you to create your first source. Each CLI process can listen to one source at a time.
  168. > The `port-or-URL` param is mandatory, events will be forwarded to http://localhost:$PORT/$DESTINATION_PATH when inputing a valid port or your provided URL.
  169. #### Interactive Mode
  170. The default interactive mode uses a full-screen TUI (Terminal User Interface) with an alternative screen buffer, meaning your terminal history is preserved when you exit. The interface includes:
  171. - **Connection Header**: Shows your sources, webhook URLs, and connection routing
  172. - Auto-collapses when the first event arrives to save space
  173. - Toggle with `i` to expand/collapse connection details
  174. - **Event List**: Scrollable history of all received events (up to 1000 events)
  175. - Auto-scrolls to show latest events as they arrive
  176. - Manual navigation pauses auto-scrolling
  177. - **Status Bar**: Shows event details and available keyboard shortcuts
  178. - **Event Details View**: Full request/response inspection with headers and body
  179. #### Interactive Keyboard Shortcuts
  180. While in interactive mode, you can use the following keyboard shortcuts:
  181. - `↑` / `↓` or `k` / `j` - Navigate between events (select different events)
  182. - `i` - Toggle connection information (expand/collapse connection details)
  183. - `r` - Retry the selected event
  184. - `o` - Open the selected event in the Hookdeck dashboard
  185. - `d` - Show detailed request/response information for the selected event (press `d` or `ESC` to close)
  186. - When details view is open: `↑` / `↓` scroll through content, `PgUp` / `PgDown` for page navigation
  187. - Press `C` to copy the complete request, `H` for request headers, or `B` for the request body; off-screen content is included
  188. - `q` - Quit the application (terminal state is restored)
  189. - `Ctrl+C` - Also quits the application
  190. The selected event is indicated by a `>` character at the beginning of the line. All actions (retry, open, details) work on the currently selected event, not just the latest one. These shortcuts are displayed in the status bar at the bottom of the screen.
  191. > **Note:** Copying to the clipboard works out of the box on macOS and Windows. On Linux and other BSD/Unix systems it requires either [`xclip`](https://github.com/astrand/xclip) or [`xsel`](https://github.com/kfish/xsel) to be installed; without one of them the copy shortcuts report an error.
  192. #### Listen to all your connections for a given source
  193. The second param, `source-alias` is used to select a specific source to listen on. By default, the CLI will start listening on all eligible connections for that source.
  194. ```sh
  195. $ hookdeck listen 3000 shopify
  196. ●── HOOKDECK CLI ──●
  197. Listening on 1 source • 2 connections • [i] Collapse
  198. Shopify Source
  199. │ Requests to → https://events.hookdeck.com/e/src_DAjaFWyyZXsFdZrTOKpuHnOH
  200. ├─ Forwards to → http://localhost:3000/webhooks/shopify/inventory (Inventory Service)
  201. └─ Forwards to → http://localhost:3000/webhooks/shopify/orders (Orders Service)
  202. 💡 Open dashboard to inspect, retry & bookmark events: https://dashboard.hookdeck.com/events/cli?team_id=...
  203. Events • [↑↓] Navigate ──────────────────────────────────────────────────────────
  204. 2025-10-12 14:32:15 [200] POST http://localhost:3000/webhooks/shopify/orders (23ms) → https://dashboard.hookdeck.com/events/evt_...
  205. > 2025-10-12 14:32:18 [200] POST http://localhost:3000/webhooks/shopify/inventory (45ms) → https://dashboard.hookdeck.com/events/evt_...
  206. ───────────────────────────────────────────────────────────────────────────────
  207. > ✓ Last event succeeded with status 200 | [r] Retry • [o] Open in dashboard • [d] Show data
  208. ```
  209. #### Listen to multiple sources
  210. `source-alias` can be a comma-separated list of source names (for example, `stripe,shopify,twilio`) or `'*'` (with quotes) to listen to all sources.
  211. ```sh
  212. $ hookdeck listen 3000 '*'
  213. ●── HOOKDECK CLI ──●
  214. Listening on 3 sources • 3 connections • [i] Collapse
  215. stripe
  216. │ Requests to → https://events.hookdeck.com/e/src_DAjaFWyyZXsFdZrTOKpuHn01
  217. └─ Forwards to → http://localhost:3000/webhooks/stripe (cli-stripe)
  218. shopify
  219. │ Requests to → https://events.hookdeck.com/e/src_DAjaFWyyZXsFdZrTOKpuHn02
  220. └─ Forwards to → http://localhost:3000/webhooks/shopify (cli-shopify)
  221. twilio
  222. │ Requests to → https://events.hookdeck.com/e/src_DAjaFWyyZXsFdZrTOKpuHn03
  223. └─ Forwards to → http://localhost:3000/webhooks/twilio (cli-twilio)
  224. 💡 Open dashboard to inspect, retry & bookmark events: https://dashboard.hookdeck.com/events/cli?team_id=...
  225. Events • [↑↓] Navigate ──────────────────────────────────────────────────────────
  226. 2025-10-12 14:35:21 [200] POST http://localhost:3000/webhooks/stripe (12ms) → https://dashboard.hookdeck.com/events/evt_...
  227. 2025-10-12 14:35:44 [200] POST http://localhost:3000/webhooks/shopify (31ms) → https://dashboard.hookdeck.com/events/evt_...
  228. > 2025-10-12 14:35:52 [200] POST http://localhost:3000/webhooks/twilio (18ms) → https://dashboard.hookdeck.com/events/evt_...
  229. ───────────────────────────────────────────────────────────────────────────────
  230. > ✓ Last event succeeded with status 200 | [r] Retry • [o] Open in dashboard • [d] Show data
  231. ```
  232. #### Listen to a subset of connections
  233. The 3rd param, `connection-query` specifies which connection with a CLI destination to adopt for listening. By default, the first connection with a CLI destination type will be used. If a connection with the specified name doesn't exist, a new connection will be created with the passed value. The connection query is checked against the `connection` name, `alias`, and the `path` values.
  234. ```sh
  235. $ hookdeck listen 3000 shopify orders
  236. ●── HOOKDECK CLI ──●
  237. Listening on 1 source • 1 connection • [i] Collapse
  238. Shopify Source
  239. │ Requests to → https://events.hookdeck.com/e/src_DAjaFWyyZXsFdZrTOKpuHnOH
  240. └─ Forwards to → http://localhost:3000/webhooks/shopify/orders (Orders Service)
  241. 💡 Open dashboard to inspect, retry & bookmark events: https://dashboard.hookdeck.com/events/cli?team_id=...
  242. Events • [↑↓] Navigate ──────────────────────────────────────────────────────────
  243. > 2025-10-12 14:38:09 [200] POST http://localhost:3000/webhooks/shopify/orders (27ms) → https://dashboard.hookdeck.com/events/evt_...
  244. ───────────────────────────────────────────────────────────────────────────────
  245. > ✓ Last event succeeded with status 200 | [r] Retry • [o] Open in dashboard • [d] Show data
  246. ```
  247. #### Changing the path events are forwarded to
  248. The `--path` flag sets the path to which events are forwarded.
  249. ```sh
  250. $ hookdeck listen 3000 shopify orders --path /events/shopify/orders
  251. ●── HOOKDECK CLI ──●
  252. Listening on 1 source • 1 connection • [i] Collapse
  253. Shopify Source
  254. │ Requests to → https://events.hookdeck.com/e/src_DAjaFWyyZXsFdZrTOKpuHnOH
  255. └─ Forwards to → http://localhost:3000/events/shopify/orders (Orders Service)
  256. 💡 Open dashboard to inspect, retry & bookmark events: https://dashboard.hookdeck.com/events/cli?team_id=...
  257. Events • [↑↓] Navigate ──────────────────────────────────────────────────────────
  258. > 2025-10-12 14:40:23 [200] POST http://localhost:3000/events/shopify/orders (19ms) → https://dashboard.hookdeck.com/events/evt_...
  259. ───────────────────────────────────────────────────────────────────────────────
  260. > ✓ Last event succeeded with status 200 | [r] Retry • [o] Open in dashboard • [d] Show data
  261. ```
  262. #### Controlling output verbosity
  263. The `--output` flag controls how events are displayed. This is useful for reducing resource usage in high-throughput scenarios or when running in the background.
  264. **Available modes:**
  265. - `interactive` (default) - Full-screen TUI with alternative screen buffer, event history, navigation, and keyboard shortcuts. Your terminal history is preserved and restored when you exit.
  266. - `compact` - Simple one-line logs for all events without interactive features. Events are appended to your terminal history.
  267. - `quiet` - Only displays fatal connection errors (network failures, timeouts), not HTTP errors
  268. All modes display connection information at startup and a connection status message.
  269. **Examples:**
  270. ```sh
  271. # Default - full interactive UI with keyboard shortcuts
  272. $ hookdeck listen 3000 shopify
  273. # Simple logging mode - prints all events as one-line logs
  274. $ hookdeck listen 3000 shopify --output compact
  275. # Quiet mode - only shows fatal connection errors
  276. $ hookdeck listen 3000 shopify --output quiet
  277. ```
  278. **Compact mode output:**
  279. ```
  280. Listening on
  281. shopify
  282. └─ Forwards to → http://localhost:3000
  283. Connected. Waiting for events...
  284. 2025-10-08 15:56:53 [200] POST http://localhost:3000 (45ms) → https://...
  285. 2025-10-08 15:56:54 [422] POST http://localhost:3000 (12ms) → https://...
  286. ```
  287. **Quiet mode output:**
  288. ```
  289. Listening on
  290. shopify
  291. └─ Forwards to → http://localhost:3000
  292. Connected. Waiting for events...
  293. 2025-10-08 15:56:53 [ERROR] Failed to POST: connection refused
  294. ```
  295. > Note: In `quiet` mode, only fatal errors are shown (connection failures, network unreachable, timeouts). HTTP error responses (4xx, 5xx) are not displayed as they are valid HTTP responses.
  296. #### Filtering events
  297. The CLI supports filtering events using Hookdeck's filter syntax. Filters allow you to receive only events that match specific conditions, reducing noise and focusing on the events you care about during development.
  298. **Filter flags:**
  299. - `--filter-body` - Filter events by request body content (JSON)
  300. - `--filter-headers` - Filter events by request headers (JSON)
  301. - `--filter-query` - Filter events by query parameters (JSON)
  302. - `--filter-path` - Filter events by request path (JSON)
  303. All filter flags accept JSON using [Hookdeck's filter syntax](https://hookdeck.com/docs/filters). You can use exact matches or operators like `$exist`, `$gte`, `$lte`, `$in`, etc.
  304. **Examples:**
  305. ```sh
  306. # Filter events by body content (only events with matching data)
  307. hookdeck listen 3000 github --filter-body '{"action": "opened"}'
  308. # Filter events with multiple conditions
  309. hookdeck listen 3000 stripe --filter-body '{"type": "charge.succeeded"}' --filter-headers '{"x-stripe-signature": {"$exist": true}}'
  310. # Filter using operators
  311. hookdeck listen 3000 api --filter-body '{"amount": {"$gte": 100}}'
  312. ```
  313. When filters are active, the CLI will display a warning message indicating which filters are applied. Only events matching all specified filter conditions will be forwarded to your local server.
  314. #### Viewing and interacting with your events
  315. Event logs for your CLI can be found at [https://dashboard.hookdeck.com/cli/events](https://dashboard.hookdeck.com/cli/events?ref=github-hookdeck-cli). Events can be replayed or saved at any time.
  316. ### Logout
  317. Logout of your Hookdeck account and clear your stored credentials.
  318. ```sh
  319. hookdeck logout
  320. ```
  321. ### Skip SSL validation
  322. When forwarding events to an HTTPS URL as the first argument to `hookdeck listen` (e.g., `https://localhost:1234/webhook`), you might encounter SSL validation errors if the destination is using a self-signed certificate.
  323. For local development scenarios, you can instruct the `listen` command to bypass this SSL certificate validation by using its `--insecure` flag. You must provide the full HTTPS URL. This flag also applies to the periodic server health checks that the CLI performs.
  324. **This is dangerous and should only be used in trusted local development environments for destinations you control.**
  325. Example of skipping SSL validation for an HTTPS destination:
  326. ```sh
  327. hookdeck listen --insecure https://<your-ssl-url-or-url:port>/ <source-alias?> <connection-query?>
  328. ```
  329. ### Disable health checks
  330. The CLI periodically checks if your local server is reachable and displays warnings if the connection fails. If these health checks cause issues in your environment, you can disable them with the `--no-healthcheck` flag:
  331. ```sh
  332. hookdeck listen --no-healthcheck 3000 <source-alias?>
  333. ```
  334. ### Version
  335. Print your CLI version and whether or not a new version is available.
  336. ```sh
  337. hookdeck version
  338. ```
  339. ### Completion
  340. Generate a shell completion script for the Hookdeck CLI. When installed via Homebrew or Scoop, completions are configured automatically.
  341. To enable completions for the current shell session:
  342. ```sh
  343. # bash
  344. source <(hookdeck completion --shell bash)
  345. # zsh
  346. source <(hookdeck completion --shell zsh)
  347. ```
  348. To install completions permanently, redirect the output to your shell's completion directory. See `hookdeck completion --help` for examples.
  349. ### Running in CI
  350. If you want to use Hookdeck in CI for tests or any other purposes, authenticate with a Project API key from the dashboard. The `ci` command exchanges it for a CLI client key stored in your config. It must be a *project* key: organization API keys are rejected, and the resulting CLI key is project-scoped, so it cannot list or switch projects.
  351. ```sh
  352. $ hookdeck ci --api-key $HOOKDECK_API_KEY
  353. Done! The Hookdeck CLI is configured in project MyProject
  354. $ hookdeck listen 3000 shopify orders
  355. ```
  356. `HOOKDECK_API_KEY` is read automatically, so you can skip the `ci` step entirely — if no credentials are stored, `listen` exchanges the Project API key for CLI credentials and saves them, then connects to **your** project:
  357. ```sh
  358. $ export HOOKDECK_API_KEY="your-project-api-key"
  359. $ hookdeck listen 3000 shopify orders
  360. ```
  361. Authentication order is `--cli-key`, then stored credentials from `hookdeck login` or `hookdeck ci`, then `HOOKDECK_API_KEY`. A real stored login is never repointed by the environment — but a temporary **guest** profile is, so a machine that once ran `listen` without credentials still uses your project once the variable is set. Replacing a guest profile is announced on stderr and discards the link to that sandbox; unset `HOOKDECK_API_KEY` if you want to keep it.
  362. Without a Project API key `listen` still falls back to a temporary guest account, which is convenient locally but has no delivery history, retries, or issue triggers. If you meant to use your own project, check that `HOOKDECK_API_KEY` is actually **set in the shell running the command** — a variable that is unset there expands to an empty string, and values in a `.env` file are not loaded automatically just because your application reads them.
  363. #### Output without a terminal
  364. `listen` defaults to `--output interactive`, a full-screen UI that needs a terminal. In CI, Docker, `nohup`, or an AI agent there is no terminal, so it automatically falls back to `--output compact` — plain, line-based logs suited to a log file:
  365. ```sh
  366. $ hookdeck listen 3000 shopify orders
  367. ⏺ Ready! Forwarding events from Shopify Source to http://localhost:3000/webhooks/shopify/orders
  368. ● 2025-10-12 14:42:55 [200] POST /webhooks/shopify/orders (34ms)
  369. ```
  370. Pass `--output compact` (or `--output quiet` for warnings and errors only) explicitly if you want the same behaviour on a machine that *does* have a terminal.
  371. ### Event Gateway
  372. The `hookdeck gateway` command provides full access to Hookdeck Event Gateway resources. Use these subcommands to manage infrastructure and inspect events:
  373. | Command group | Description |
  374. |---------------|-------------|
  375. | `hookdeck gateway connection` | Create and manage connections between sources and destinations |
  376. | `hookdeck gateway source` | Manage inbound webhook sources |
  377. | `hookdeck gateway destination` | Manage destinations (HTTP endpoints, CLI, etc.) |
  378. | `hookdeck gateway event` | List, get, retry, cancel, or mute events (processed deliveries) |
  379. | `hookdeck gateway request` | List, get, and retry requests (raw inbound webhooks) |
  380. | `hookdeck gateway attempt` | List and get delivery attempts |
  381. | `hookdeck gateway transformation` | Create and manage JavaScript transformations |
  382. **Examples:**
  383. ```sh
  384. # List sources and destinations
  385. hookdeck gateway source list
  386. hookdeck gateway destination list
  387. # List events (processed deliveries) and requests (raw inbound webhooks)
  388. hookdeck gateway event list --status FAILED
  389. hookdeck gateway request list --source-id src_abc123
  390. # List attempts for an event
  391. hookdeck gateway attempt list --event-id evt_abc123
  392. # Create a transformation and test-run it
  393. hookdeck gateway transformation create --name my-transform --code "addHandler(\"transform\", (request, context) => { return request; });"
  394. hookdeck gateway transformation run --code "addHandler(\"transform\", (request, context) => { return request; });" --request '{"headers":{}}'
  395. ```
  396. For complete command and flag reference, see [REFERENCE.md](REFERENCE.md).
  397. ### Event Gateway MCP
  398. The CLI includes an [MCP](https://modelcontextprotocol.io/) (Model Context Protocol) server for investigating event traffic in production. It exposes read-only tools that let AI agents query your Hookdeck Event Gateway — inspect connections, trace requests through events and delivery attempts, review issues, and pull aggregate metrics.
  399. **Configure your MCP client** (Cursor, Claude Desktop, or any MCP-compatible host):
  400. Cursor (`~/.cursor/mcp.json`):
  401. ```json
  402. {
  403. "mcpServers": {
  404. "hookdeck": {
  405. "command": "hookdeck",
  406. "args": ["gateway", "mcp"]
  407. }
  408. }
  409. }
  410. ```
  411. Claude Desktop (`claude_desktop_config.json`):
  412. ```json
  413. {
  414. "mcpServers": {
  415. "hookdeck": {
  416. "command": "hookdeck",
  417. "args": ["gateway", "mcp"]
  418. }
  419. }
  420. }
  421. ```
  422. The client starts `hookdeck gateway mcp` as a stdio subprocess. If you haven't authenticated yet, the `hookdeck_login` tool is available to log in via the browser.
  423. #### Read-only by default
  424. The server starts read-only. Tools advertise only the actions that read data, so an agent is never offered an action it cannot perform. Pass `--allow-write` (or set `HOOKDECK_MCP_ALLOW_WRITE=true`) to enable creating, changing and deleting:
  425. ```json
  426. {
  427. "mcpServers": {
  428. "hookdeck": {
  429. "command": "hookdeck",
  430. "args": ["gateway", "mcp", "--allow-write"]
  431. }
  432. }
  433. }
  434. ```
  435. `--read-only` is accepted explicitly and wins if both are passed.
  436. Pausing and unpausing a connection are available in **both** modes. Read-only is the mode incidents get investigated in, and stopping a misbehaving connection is the natural end of an investigation; both are reversible, and pausing buffers delivery rather than dropping events.
  437. #### Available tools
  438. Product tools are prefixed `gateway_`. Signing in and switching project are Hookdeck operations rather than Event Gateway ones, so they keep the platform `hookdeck_` prefix and are shared with `hookdeck outpost mcp`.
  439. | Read tool (both modes) | Actions | Write tool (`--allow-write` only) | Actions |
  440. |---|---|---|---|
  441. | `hookdeck_projects_read` | list | — | — |
  442. | `hookdeck_projects_use` | use | — | — |
  443. | `hookdeck_login` | (sign in) | — | — |
  444. | `gateway_connections_read` | list, get | `gateway_connections_write` | create, upsert, update, delete, enable, disable |
  445. | `gateway_connections_pause` | pause, unpause | — | — |
  446. | `gateway_sources_read` | list, get | `gateway_sources_write` | create, upsert, update, delete, enable, disable |
  447. | `gateway_destinations_read` | list, get | `gateway_destinations_write` | create, upsert, update, delete, enable, disable |
  448. | `gateway_transformations_read` | list, get, run | `gateway_transformations_write` | create, upsert, update, delete |
  449. | `gateway_requests_read` | list | — | — |
  450. | `gateway_request_read` | get, raw_body | `gateway_request_write` | retry |
  451. | `gateway_events_read` | list, list_ignored | — | — |
  452. | `gateway_event_read` | get, raw_body | `gateway_event_write` | retry, cancel, mute |
  453. | `gateway_attempts_read` | list, get | — | — |
  454. | `gateway_issues_read` | list, get | `gateway_issues_write` | update, dismiss |
  455. | `gateway_metrics_read` | events, requests, attempts, transformations | — | — |
  456. | `gateway_bulk_read` | list, get, plan | `gateway_bulk_write` | create, cancel |
  457. | `gateway_help` | overview, per-tool topics | — | — |
  458. Every tool name ends in `_read` or `_write`, so a client that grants permission per tool name can
  459. allow all reads with one rule — `mcp__hookdeck-gateway__*_read` — and be prompted on everything
  460. that changes data. A read tool is identical in both modes, so a grant written against one keeps
  461. meaning the same thing after the server is restarted with `--allow-write`.
  462. Two tools match neither suffix, and both are deliberate. `gateway_connections_pause` changes
  463. delivery but stays available without `--allow-write`, because pausing a misbehaving connection is
  464. usually how an investigation ends. `hookdeck_projects_use` changes which project every later call
  465. targets, and gating it would strand a read-only session in whichever project it started in.
  466. `gateway_bulk_read`'s `plan` action estimates how many records a bulk operation would touch
  467. without running it — so the blast radius of a bulk retry or replay can be sized with no write
  468. access at all.
  469. API key management is deliberately **not** exposed to MCP in any form. A key is a credential, and
  470. an agent able to mint one could grant itself access this server would otherwise refuse. Use the
  471. Hookdeck dashboard.
  472. `transformations run` executes code without storing anything, but it is gated as a write: a read-only session should not be able to run caller-supplied code.
  473. Events and requests are each split into a **plural** tool that searches and a **singular** tool that acts on one record:
  474. - `gateway_events_read` / `gateway_requests_read` (plural) take the filters and return IDs. They cannot fetch or change a single record.
  475. - `gateway_event_read` / `gateway_request_read` (singular) take an `id` and nothing else (plus `connection_ids` on request retry). They cannot search.
  476. The usual flow is plural to find an ID, then singular with that ID. The split keeps ~20 list filters out of the schema for actions that only need an id.
  477. `gateway_events_read` and `gateway_requests_read` **list** actions support the same filters as `hookdeck gateway event list` and `hookdeck gateway request list` — including payload search (`body`, `headers`, `parsed_query`, `path`) and date windows via `*_after` / `*_before` (ISO 8601; maps to API `field[gte]` / `field[lte]`). See `gateway_help` with topic `gateway_events_read` or `gateway_requests_read` for the full parameter list.
  478. Both **list** actions also take `include: "data"`, which returns each event's or request's payload (headers, body, path, parsed query) in the list itself, so an agent that needs several payloads makes one call instead of one per record. Payloads make responses much larger, so pair it with a small `limit` and page with `next`. When `include` is set without a `limit`, the tool sends `limit=10` rather than the API's default page size. `list_ignored` does not take it: its route does not declare `include`. On the command line, the same option is `--include data` on `gateway event list`, `gateway request list` and `gateway request events`; it requires `--output json`, and the limit defaults to 10 there too.
  479. The only relationship traversal the API supports is request → events, and `gateway_events_read` owns both directions of it. Pass `request_id` with action `list` for the events a request produced, or action `list_ignored` for the ones a connection filter dropped. `GET /events` declares no `request_id` filter, so the tool queries the request's own events route instead — it takes the same filters, so every argument still applies (`list_ignored`'s route is the exception: it takes `id`, paging and ordering only). There is no `event_id` filter on requests. To go the other way, read `request_id` off an event and call `gateway_request_read` with action `get`.
  480. `gateway_help` reports which mode the session is in and lists only the actions it can perform.
  481. #### Example prompts
  482. Once the MCP server is configured, you can ask your agent questions like:
  483. ```
  484. "Are any of my events failing right now?"
  485. → Agent uses gateway_issues to list open issues, then gateway_events to inspect recent failures.
  486. "Show me the last 10 events for my Stripe source and check if any failed."
  487. → Agent uses gateway_sources to find the Stripe source, then gateway_events filtered by source and status.
  488. "What's the error rate for my API destination over the last 24 hours?"
  489. → Agent uses gateway_metrics with measures like failed_count and count, grouped by destination.
  490. "Trace request req_abc123 — what events did it produce, and did they all deliver successfully?"
  491. → Agent uses gateway_request to get the request, then its events action to list generated events.
  492. "Why is my checkout endpoint returning 500s? Show me the latest attempt details."
  493. → Agent uses gateway_events filtered by status FAILED, then gateway_attempts to inspect delivery details.
  494. "Pause the connection between Stripe and my staging endpoint while I debug."
  495. → Agent uses gateway_connections_read to find it, then gateway_connections_pause to stop delivery.
  496. "Compare failure rates across all my destinations this week."
  497. → Agent uses gateway_metrics with dimensions set to destination_id and measures like error_rate.
  498. "Find Stripe charge.succeeded events from the last week."
  499. → Agent uses gateway_events list with body filter {"type":"charge.succeeded"} and created_after / created_before ISO datetimes.
  500. "Show failed events that had delivery attempts in the last 24 hours."
  501. → Agent uses gateway_events list with status FAILED and last_attempt_after set to yesterday's ISO datetime.
  502. ```
  503. ### Outpost
  504. Manage [Hookdeck Outpost](https://hookdeck.com/docs/outpost) — your users (tenants), the destinations they own, and the events delivered to them.
  505. These commands require an Outpost project. Switch with `hookdeck project use`; pointing them at an Event Gateway project reports which type the project is rather than failing obscurely.
  506. ```sh
  507. hookdeck outpost [command]
  508. # Available commands
  509. hookdeck outpost tenant # Manage tenants
  510. hookdeck outpost destination # Manage a tenant's destinations
  511. hookdeck outpost destination-type # Inspect available destination types and their fields
  512. hookdeck outpost event # Inspect published events, and retry delivery
  513. hookdeck outpost attempt # Inspect delivery attempts
  514. hookdeck outpost publish # Publish an event
  515. hookdeck outpost topic # Inspect available topics
  516. hookdeck outpost metrics # Query aggregate metrics
  517. hookdeck outpost config # Manage project configuration and the portal domain
  518. hookdeck outpost status # Show the deployment status
  519. ```
  520. #### Destination config
  521. Config and credential fields differ per destination type, and are defined by the Outpost deployment rather than the CLI, so they are passed as repeatable `key=value` pairs:
  522. ```sh
  523. hookdeck outpost tenant upsert acme
  524. hookdeck outpost destination create --tenant-id acme --type webhook \
  525. --config url=https://example.com/hooks --topics user.created
  526. ```
  527. To find out what a type accepts, either ask for it directly or add `--type` to `--help`:
  528. ```sh
  529. hookdeck outpost destination-type get kafka
  530. hookdeck outpost destination create --type kafka --help
  531. ```
  532. Both list every field with whether it is required, whether it is sensitive, and any values or format it is constrained to. `--config-file` accepts a JSON object, and nested values — should a type ever need them — use dotted paths (`--config a.b=c`).
  533. Tenants and destinations also carry `--metadata key=value` (repeatable, or `--metadata-file` for a JSON object) for your own correlation data. It is replaced wholesale rather than merged, so pass every key you want to keep.
  534. #### Publishing
  535. `hookdeck outpost publish` is the one command that does **not** use the credentials stored by `hookdeck login`. The publish API requires a Hookdeck **Project API key**, so pass `--api-key` or set `HOOKDECK_API_KEY`:
  536. ```sh
  537. hookdeck outpost publish --tenant-id acme --topic user.created \
  538. --data '{"user_id":"123"}' --api-key $HOOKDECK_API_KEY
  539. ```
  540. Create a Project API key in the Hookdeck dashboard under your project's settings. See [CLI authentication keys](#cli-authentication-keys) for how the key types differ.
  541. Publishing is asynchronous: a successful response means the event was accepted, not delivered. Use `hookdeck outpost attempt list` to see the outcome.
  542. For complete command and flag reference, see [REFERENCE.md](REFERENCE.md).
  543. ### Outpost MCP
  544. `hookdeck outpost mcp` starts an [MCP](https://modelcontextprotocol.io/) server exposing your Outpost project to AI agents: tenants, their destinations, the events published to them, and every delivery attempt. Tools are prefixed `outpost_`, so this server and [Event Gateway MCP](#event-gateway-mcp) can be configured in the same client.
  545. ```json
  546. {
  547. "mcpServers": {
  548. "hookdeck-outpost": {
  549. "command": "hookdeck",
  550. "args": ["outpost", "mcp"]
  551. }
  552. }
  553. }
  554. ```
  555. The client starts `hookdeck outpost mcp` as a stdio subprocess. If you haven't authenticated yet, the `hookdeck_login` tool logs in via the browser. The active project must be an Outpost project; `hookdeck_projects_read` lists the Outpost projects available to you and switches between them. Signing in and switching projects are Hookdeck operations rather than Outpost ones, so they keep the `hookdeck_` prefix in both servers.
  556. #### Read-only by default
  557. The server starts read-only. Each tool advertises only the actions that read data, so an agent is never offered an action it cannot perform. Add `--allow-write` (or set `HOOKDECK_MCP_ALLOW_WRITE=true`; the flag wins) to enable the rest:
  558. ```json
  559. "args": ["outpost", "mcp", "--allow-write"]
  560. ```
  561. `--read-only` is accepted as an explicit way to ask for the default, and wins if both are passed.
  562. Two actions that only read are gated with the writes, because both return a reusable credential: `outpost_tenants_write` `token` mints a tenant-scoped access token, and `outpost_tenants_read` `portal` returns a URL granting access to a tenant's portal.
  563. Publishing needs a Hookdeck **Project API key**, which the credentials stored by `hookdeck login` cannot substitute for. Without one the `outpost_publish_write` tool is not registered at all; pass `--publish-api-key` or set `HOOKDECK_OUTPOST_PUBLISH_API_KEY` to enable it.
  564. `HOOKDECK_API_KEY` is deliberately **not** read here. Elsewhere in the CLI it means "a key to exchange for CLI credentials" and is commonly exported for CI, so reading it here would let an ambient variable silently grant an agent the ability to publish real events to real destinations.
  565. #### Available tools
  566. | Tool | Description |
  567. |------|-------------|
  568. | `hookdeck_login` | Sign in via the browser |
  569. | `hookdeck_projects_read` / `_use` | List the projects this credential can see, and switch the active one |
  570. | `outpost_tenants_read` / `_write` | Inspect tenants (list, get); manage them (upsert, delete, token, portal) |
  571. | `outpost_destinations_read` / `_write` | Inspect a tenant's destinations (list, get); manage them (create, update, delete, enable, disable) |
  572. | `outpost_events_read` / `_write` | Query published events (list, get); retry delivery |
  573. | `outpost_attempts_read` | Query delivery attempts — status, response codes, retry history |
  574. | `outpost_publish_write` | Publish an event to a topic |
  575. | `outpost_topics_read` | List the topics available in the project |
  576. | `outpost_destination_types_read` | Inspect destination types and the config and credential fields each accepts |
  577. | `outpost_metrics_read` | Query aggregate publish and delivery metrics |
  578. | `outpost_config_read` / `_write` | Read and change project configuration, including the portal's custom domain |
  579. | `outpost_status_read` | Show the deployment status |
  580. | `outpost_help` | Discover the available tools, their actions, and the current mode |
  581. Call `outpost_help` at any time to see which mode the session is in and which actions it can perform.
  582. ### Manage connections
  583. Create and manage webhook connections between sources and destinations with inline resource creation, authentication, processing rules, and lifecycle management. Use `hookdeck gateway connection` (or the backward-compatible alias `hookdeck connection`). For detailed examples with authentication, filters, retry rules, and rate limiting, see the complete [connection management](#manage-connections) section below.
  584. ```sh
  585. hookdeck gateway connection [command]
  586. # Available commands
  587. hookdeck gateway connection list # List all connections
  588. hookdeck gateway connection get # Get connection details
  589. hookdeck gateway connection create # Create a new connection
  590. hookdeck gateway connection upsert # Create or update a connection (idempotent)
  591. hookdeck gateway connection update # Update a connection
  592. hookdeck gateway connection delete # Delete a connection
  593. hookdeck gateway connection enable # Enable a connection
  594. hookdeck gateway connection disable # Disable a connection
  595. hookdeck gateway connection pause # Pause a connection
  596. hookdeck gateway connection unpause # Unpause a connection
  597. ```
  598. #### Sources and destinations
  599. You can manage sources and destinations independently, not only inline when creating connections. Create reusable sources (e.g. Stripe, GitHub) and destinations (HTTP endpoints) that multiple connections can reference.
  600. ```sh
  601. # List and inspect sources and destinations
  602. hookdeck gateway source list
  603. hookdeck gateway source get src_abc123
  604. hookdeck gateway destination list
  605. hookdeck gateway destination get dst_abc123
  606. # Create a standalone destination
  607. hookdeck gateway destination create --name "my-api" --type HTTP --url "https://api.example.com/webhooks"
  608. ```
  609. See [Sources](REFERENCE.md#sources) and [Destinations](REFERENCE.md#destinations) in REFERENCE.md.
  610. ### Transformations
  611. Transformations are JavaScript modules that modify requests before delivery. They are attached to connections and can add headers, transform the body, or filter events. Create, test, and manage transformations with `hookdeck gateway transformation`:
  612. ```sh
  613. # Create a transformation
  614. hookdeck gateway transformation create --name my-transform --code "addHandler(\"transform\", (request, context) => { return request; });"
  615. # Test run transformation code (see transformed output)
  616. hookdeck gateway transformation run --code "addHandler(\"transform\", (request, context) => { return request; });" --request '{"headers":{}}'
  617. # List and use with connections (--transformation-name when creating connections)
  618. hookdeck gateway transformation list
  619. ```
  620. See [Transformations](REFERENCE.md#transformations) in REFERENCE.md.
  621. ### Requests, events, and attempts
  622. Webhooks flow through Hookdeck as **requests** (raw inbound), then **events** (processed, routed), then **attempts** (delivery tries). Use these commands to inspect, filter, and retry:
  623. ```sh
  624. # List requests (raw inbound webhooks) and filter by source
  625. hookdeck gateway request list --source-id src_abc123
  626. hookdeck gateway request get req_abc123
  627. # List events (processed deliveries) by status
  628. hookdeck gateway event list --status FAILED
  629. hookdeck gateway event list --status PENDING
  630. hookdeck gateway event get evt_abc123
  631. # Retry a failed event or request
  632. hookdeck gateway event retry evt_abc123
  633. hookdeck gateway request retry req_abc123
  634. # List attempts (individual delivery tries) for an event
  635. hookdeck gateway attempt list --event-id evt_abc123
  636. ```
  637. See [Requests](REFERENCE.md#requests), [Events](REFERENCE.md#events), and [Attempts](REFERENCE.md#attempts) in REFERENCE.md.
  638. ### Manage active project
  639. If you are a part of multiple projects, you can switch between them using our project management commands.
  640. #### List projects
  641. ```sh
  642. # List all projects
  643. $ hookdeck project list
  644. My Org / My Project (current)
  645. My Org / Another Project
  646. Another Org / Yet Another One
  647. # Filter by organization and project name
  648. $ hookdeck project list Org Proj
  649. My Org / My Project (current)
  650. My Org / Another Project
  651. ```
  652. #### Select active project
  653. ```console
  654. hookdeck project use [<organization_name> [<project_name>]] [--local]
  655. Flags:
  656. --local Save project to current directory (.hookdeck/config.toml)
  657. ```
  658. **Project Selection Modes:**
  659. - **No arguments**: Interactive prompt to select organization and project
  660. - **One argument**: Filter by organization name (prompts if multiple projects)
  661. - **Two arguments**: Directly select organization and project
  662. ```sh
  663. $ hookdeck project use my-org my-project
  664. Successfully set active project to: my-org / my-project
  665. ```
  666. #### Configuration scope: Global vs Local
  667. By default, `project use` saves your selection to the **global configuration** (`~/.config/hookdeck/config.toml`). You can pin a specific project to the **current directory** using the `--local` flag.
  668. **Configuration file precedence (only ONE is used):**
  669. The CLI uses exactly one configuration file based on this precedence:
  670. 1. **Custom config** (via `--hookdeck-config` flag) - highest priority
  671. 2. **Local config** - `${PWD}/.hookdeck/config.toml` (if exists)
  672. 3. **Global config** - `~/.config/hookdeck/config.toml` (default)
  673. Unlike Git, Hookdeck **does not merge** multiple config files - only the highest precedence config is used.
  674. **Examples:**
  675. ```sh
  676. # No local config exists → saves to global
  677. $ hookdeck project use my-org my-project
  678. Successfully set active project to: my-org / my-project
  679. Saved to: ~/.config/hookdeck/config.toml
  680. # Local config exists → automatically updates local
  681. $ cd ~/repo-with-local-config # has .hookdeck/config.toml
  682. $ hookdeck project use another-org another-project
  683. Successfully set active project to: another-org / another-project
  684. Updated: .hookdeck/config.toml
  685. # Create new local config
  686. $ cd ~/my-new-repo # no .hookdeck/ directory
  687. $ hookdeck project use my-org my-project --local
  688. Successfully set active project to: my-org / my-project
  689. Created: .hookdeck/config.toml
  690. ⚠️ Security: Add .hookdeck/ to .gitignore (contains credentials)
  691. # Update existing local config with confirmation
  692. $ hookdeck project use another-org another-project --local
  693. Local configuration already exists at: .hookdeck/config.toml
  694. ? Overwrite with new project configuration? (y/N) y
  695. Successfully set active project to: another-org / another-project
  696. Updated: .hookdeck/config.toml
  697. ```
  698. **Smart default behavior:**
  699. When you run `project use` with neither `--local` nor `--hookdeck-config`:
  700. - **If `.hookdeck/config.toml` exists**: Updates the local config
  701. - **Otherwise**: Updates the global config
  702. This ensures your directory-specific configuration is preserved when it exists.
  703. An explicit flag always beats this discovery. With `--hookdeck-config <path>`, that file is
  704. the one read and the one written, even when the working directory contains
  705. `.hookdeck/config.toml`:
  706. ```sh
  707. $ cd ~/repo-with-local-config # has .hookdeck/config.toml
  708. $ hookdeck --hookdeck-config ~/ci.toml project use my-org my-project
  709. Successfully set active project to: my-org / my-project
  710. Saved to: ~/ci.toml # the local config is untouched
  711. ```
  712. **Flag validation:**
  713. ```sh
  714. # ✅ Valid
  715. hookdeck project use my-org my-project
  716. hookdeck project use my-org my-project --local
  717. # ❌ Invalid (cannot combine --hookdeck-config with --local)
  718. hookdeck --hookdeck-config custom.toml project use my-org my-project --local
  719. Error: --local and --hookdeck-config flags cannot be used together
  720. --local creates config at: .hookdeck/config.toml
  721. --hookdeck-config uses custom path: custom.toml
  722. ```
  723. #### Benefits of local project pinning
  724. - **Per-repository configuration**: Each repository can use a different Hookdeck project
  725. - **Team collaboration**: Commit `.hookdeck/config.toml` to private repos (see security note)
  726. - **No context switching**: Automatically uses the right project when you `cd` into a directory
  727. - **CI/CD friendly**: Works seamlessly in automated environments
  728. #### Security: Config files and source control
  729. ⚠️ **IMPORTANT**: Configuration files contain your Hookdeck credentials and should be treated as sensitive.
  730. Config files store a **CLI client key** as `api_key` after `hookdeck login`, `hookdeck login --cli-key`, or `hookdeck ci`.
  731. **Recommended practices:**
  732. - **Private repositories**: You MAY commit `.hookdeck/config.toml` if your repository is guaranteed to remain private and all collaborators should have access to the credentials.
  733. - **Public repositories**: You MUST add `.hookdeck/` to your `.gitignore`:
  734. ```gitignore
  735. # Hookdeck CLI configuration (contains credentials)
  736. .hookdeck/
  737. ```
  738. - **CI/CD environments**: Use a Project API key via `HOOKDECK_API_KEY` (see [Running in CI](#running-in-ci)). `hookdeck ci` is optional — `listen` reads the variable itself:
  739. ```sh
  740. export HOOKDECK_API_KEY="your-project-api-key"
  741. hookdeck listen 3000
  742. ```
  743. To keep credentials out of the shared global config entirely, pass `--hookdeck-config <path>`, or use `hookdeck ci --local` to write only `.hookdeck/config.toml` in the working directory.
  744. **Checking which config is active:**
  745. ```sh
  746. $ hookdeck whoami
  747. Logged in as: user@example.com
  748. Active project: my-org / my-project
  749. Config file: /Users/username/my-repo/.hookdeck/config.toml (local)
  750. ```
  751. **Removing local configuration:**
  752. To stop using local configuration and switch back to global:
  753. ```sh
  754. $ rm -rf .hookdeck/
  755. # Now CLI uses global config
  756. ```
  757. ### Manage connections
  758. Connections link sources to destinations and define how events are processed. You can create connections, including source/destination definitions, configure authentication, add processing rules (retry, filter, transform, delay, deduplicate), and manage their lifecycle.
  759. #### Create a connection
  760. Create a new connection between a source and destination. You can create the source and destination inline or reference existing resources:
  761. ```sh
  762. # Basic connection with inline source and destination
  763. $ hookdeck gateway connection create \
  764. --source-name "github-repo" \
  765. --source-type GITHUB \
  766. --destination-name "ci-system" \
  767. --destination-type HTTP \
  768. --destination-url "https://api.example.com/webhooks"
  769. ✔ Connection created successfully
  770. Connection: github-repo-to-ci-system (conn_abc123)
  771. Source: github-repo (src_xyz789)
  772. Source URL: https://hkdk.events/src_xyz789
  773. Destination: ci-system (dst_def456)
  774. # Using existing source and destination
  775. $ hookdeck gateway connection create \
  776. --source-id src_existing123 \
  777. --destination-id dst_existing456 \
  778. --name "new-connection" \
  779. --description "Connects existing resources"
  780. ```
  781. #### Add source authentication
  782. Verify webhooks from providers like Stripe, GitHub, or Shopify by adding source authentication:
  783. ```sh
  784. # Stripe webhook signature verification
  785. $ hookdeck gateway connection create \
  786. --source-name "stripe-prod" \
  787. --source-type STRIPE \
  788. --source-webhook-secret "whsec_abc123xyz" \
  789. --destination-name "payment-api" \
  790. --destination-type HTTP \
  791. --destination-url "https://api.example.com/webhooks/stripe"
  792. # GitHub webhook signature verification
  793. $ hookdeck gateway connection create \
  794. --source-name "github-webhooks" \
  795. --source-type GITHUB \
  796. --source-webhook-secret "ghp_secret123" \
  797. --destination-name "ci-system" \
  798. --destination-type HTTP \
  799. --destination-url "https://ci.example.com/webhook"
  800. ```
  801. #### Add destination authentication
  802. Secure your destination endpoint with bearer tokens, API keys, or basic authentication:
  803. ```sh
  804. # Destination with bearer token
  805. $ hookdeck gateway connection create \
  806. --source-name "webhook-source" \
  807. --source-type HTTP \
  808. --destination-name "secure-api" \
  809. --destination-type HTTP \
  810. --destination-url "https://api.example.com/webhooks" \
  811. --destination-bearer-token "bearer_token_xyz"
  812. # Destination with API key
  813. $ hookdeck gateway connection create \
  814. --source-name "webhook-source" \
  815. --source-type HTTP \
  816. --destination-name "api-endpoint" \
  817. --destination-type HTTP \
  818. --destination-url "https://api.example.com/webhooks" \
  819. --destination-api-key "your_api_key"
  820. # Destination with custom headers
  821. $ hookdeck gateway connection create \
  822. --source-name "webhook-source" \
  823. --source-type HTTP \
  824. --destination-name "custom-api" \
  825. --destination-type HTTP \
  826. --destination-url "https://api.example.com/webhooks"
  827. ```
  828. #### Configure retry rules
  829. Add automatic retry logic with exponential or linear backoff:
  830. ```sh
  831. # Exponential backoff retry strategy
  832. $ hookdeck gateway connection create \
  833. --source-name "payment-webhooks" \
  834. --source-type STRIPE \
  835. --destination-name "payment-api" \
  836. --destination-type HTTP \
  837. --destination-url "https://api.example.com/payments" \
  838. --rule-retry-strategy exponential \
  839. --rule-retry-count 5 \
  840. --rule-retry-interval 60000
  841. ```
  842. #### Add event filters
  843. Filter events based on request body, headers, path, or query parameters:
  844. ```sh
  845. # Filter by event type in body
  846. $ hookdeck gateway connection create \
  847. --source-name "events" \
  848. --source-type HTTP \
  849. --destination-name "processor" \
  850. --destination-type HTTP \
  851. --destination-url "https://api.example.com/process" \
  852. --rule-filter-body '{"event_type":"payment.succeeded"}'
  853. # Combined filtering
  854. $ hookdeck gateway connection create \
  855. --source-name "shopify-webhooks" \
  856. --source-type SHOPIFY \
  857. --destination-name "order-processor" \
  858. --destination-type HTTP \
  859. --destination-url "https://api.example.com/orders" \
  860. --rule-filter-body '{"type":"order"}' \
  861. --rule-retry-strategy exponential \
  862. --rule-retry-count 3
  863. ```
  864. Rules built from `--rule-*` flags follow the order in which each rule type's first flag appears. Filter, transform and deduplicate rules run in that order, so put `--rule-filter-*` before `--rule-transform-*` to filter on the original payload. To set the whole array explicitly, use `--rules` or `--rules-file`.
  865. #### Configure rate limiting
  866. Control the rate of event delivery to your destination:
  867. ```sh
  868. # Limit to 100 requests per minute
  869. $ hookdeck gateway connection create \
  870. --source-name "high-volume-source" \
  871. --source-type HTTP \
  872. --destination-name "rate-limited-api" \
  873. --destination-type HTTP \
  874. --destination-url "https://api.example.com/endpoint" \
  875. --destination-rate-limit 100 \
  876. --destination-rate-limit-period minute
  877. ```
  878. #### Configure delivery groups
  879. Isolate delivery queues by a payload field and optionally give selected groups a different maximum rate:
  880. ```sh
  881. $ hookdeck gateway connection create \
  882. --name "tenant-aware-delivery" \
  883. --source-name "events" \
  884. --source-type HTTP \
  885. --destination-name "tenant-aware-api" \
  886. --destination-type HTTP \
  887. --destination-url "https://api.example.com/endpoint" \
  888. --destination-rate-limit 100 \
  889. --destination-rate-limit-period second \
  890. --destination-delivery-group-key body.customer_id \
  891. --destination-delivery-group-rate 5 \
  892. --destination-delivery-group-rate-period second \
  893. --destination-delivery-group-overrides '{"cus_priority":{"rate":50,"rate_period":"second"}}'
  894. ```
  895. Use `--config` or `--config-file` when you need to set `delivery_policy.groups` directly, including setting `groups` to `null` to disable grouping.
  896. #### Upsert connections
  897. Create or update connections idempotently based on connection name - perfect for CI/CD and infrastructure-as-code workflows:
  898. ```sh
  899. # Create if doesn't exist, update if it does
  900. $ hookdeck gateway connection upsert my-connection \
  901. --source-name "stripe-prod" \
  902. --source-type STRIPE \
  903. --destination-name "api-prod" \
  904. --destination-type HTTP \
  905. --destination-url "https://api.example.com"
  906. # Partial update of existing connection
  907. $ hookdeck gateway connection upsert my-connection \
  908. --description "Updated description" \
  909. --rule-retry-count 5
  910. # Preview changes without applying (dry-run)
  911. $ hookdeck gateway connection upsert my-connection \
  912. --description "New description" \
  913. --dry-run
  914. -- Dry Run: UPDATE --
  915. Connection 'my-connection' (conn_123) will be updated with the following changes:
  916. - Description: "New description"
  917. ```
  918. #### List and filter connections
  919. View all connections with flexible filtering options:
  920. ```sh
  921. # List all connections
  922. $ hookdeck gateway connection list
  923. # Filter by source or destination
  924. $ hookdeck gateway connection list --source-id src_abc123
  925. $ hookdeck gateway connection list --destination-id dst_def456
  926. # Filter by name pattern
  927. $ hookdeck gateway connection list --name "production-*"
  928. # Include disabled connections
  929. $ hookdeck gateway connection list --disabled
  930. # Output as JSON
  931. $ hookdeck gateway connection list --output json
  932. ```
  933. #### Get connection details
  934. View detailed information about a specific connection:
  935. ```sh
  936. # Get by ID
  937. $ hookdeck gateway connection get conn_123abc
  938. # Get by name
  939. $ hookdeck gateway connection get "my-connection"
  940. # Get as JSON
  941. $ hookdeck gateway connection get conn_123abc --output json
  942. # Include destination authentication credentials
  943. $ hookdeck gateway connection get conn_123abc --include-destination-auth --output json
  944. ```
  945. #### Connection lifecycle management
  946. Control connection state and event processing behavior:
  947. ```sh
  948. # Disable a connection (stops receiving events entirely)
  949. $ hookdeck gateway connection disable conn_123abc
  950. # Enable a disabled connection
  951. $ hookdeck gateway connection enable conn_123abc
  952. # Pause a connection (queues events without forwarding)
  953. $ hookdeck gateway connection pause conn_123abc
  954. # Resume a paused connection
  955. $ hookdeck gateway connection unpause conn_123abc
  956. ```
  957. **State differences:**
  958. - **Disabled**: Connection stops receiving events entirely
  959. - **Paused**: Connection queues events but doesn't forward them (useful during maintenance)
  960. #### Delete a connection
  961. Delete a connection permanently:
  962. ```sh
  963. # Delete with confirmation prompt
  964. $ hookdeck gateway connection delete conn_123abc
  965. # Delete by name
  966. $ hookdeck gateway connection delete "my-connection"
  967. # Skip confirmation
  968. $ hookdeck gateway connection delete conn_123abc --force
  969. ```
  970. For complete flag documentation and all examples, see [REFERENCE.md](REFERENCE.md).
  971. ### Telemetry
  972. The Hookdeck CLI collects anonymous telemetry to help improve the tool. You can opt out at any time:
  973. ```sh
  974. # Disable telemetry
  975. hookdeck telemetry disabled
  976. # Re-enable telemetry
  977. hookdeck telemetry enabled
  978. ```
  979. You can also disable telemetry by setting the `HOOKDECK_CLI_TELEMETRY_DISABLED` environment variable to `1` or `true`.
  980. ## Configuration files
  981. The Hookdeck CLI uses configuration files to store the your keys, project settings, profiles, and other configurations.
  982. ### Configuration file name and locations
  983. The CLI will look for the configuration file in the following order:
  984. 1. The `--hookdeck-config` flag, which allows you to specify a custom configuration file path per command.
  985. 2. The `HOOKDECK_CONFIG_FILE` environment variable (path to the config file).
  986. 3. The local directory `.hookdeck/config.toml`.
  987. 4. The default global configuration file location.
  988. The file chosen this way is the file the CLI reads **and** writes. An explicit path beats
  989. discovery: pass `--hookdeck-config <path>` and no other configuration file is touched, whatever
  990. the working directory contains. `--local` (on `login`, `ci` and `project use`) instead pins both
  991. to `./.hookdeck/config.toml`, and cannot be combined with `--hookdeck-config`.
  992. ### Default configuration Location
  993. The default configuration location varies by operating system:
  994. - **macOS/Linux**: `~/.config/hookdeck/config.toml`
  995. - **Windows**: `%USERPROFILE%\.config\hookdeck\config.toml`
  996. The CLI follows the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) on Unix-like systems, respecting the `XDG_CONFIG_HOME` environment variable if set.
  997. ### Configuration File Format
  998. The Hookdeck CLI configuration file is stored in TOML format and typically includes:
  999. ```toml
  1000. api_key = "api_key_xxxxxxxxxxxxxxxxxxxx"
  1001. project_id = "tm_xxxxxxxxxxxxxxx"
  1002. project_type = "Gateway" | "Outpost" | "Console"
  1003. ```
  1004. ### Local Configuration
  1005. The Hookdeck CLI also supports local configuration files. If you run the CLI commands in a directory that contains a `.hookdeck/config.toml` file, the CLI will use that file for configuration instead of the global one.
  1006. ### Using Profiles
  1007. The `config.toml` file supports profiles which give you the ability to save different CLI configuration within the same configuration file.
  1008. You can create new profiles by either running `hookdeck login` or `hookdeck use` with the `-p` flag and a profile name. For example:
  1009. ```sh
  1010. hookdeck login -p dev
  1011. ```
  1012. If you know the name of your Hookdeck organization and the project you want to use with a profile you can use the following:
  1013. ```sh
  1014. hookdeck project use org_name proj_name -p prod
  1015. ```
  1016. This will results in the following config file that has two profiles:
  1017. ```toml
  1018. profile = "dev"
  1019. [dev]
  1020. api_key = "api_key_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  1021. project_id = "tm_5JxTelcYxOJy"
  1022. project_type = "Gateway"
  1023. [prod]
  1024. api_key = "api_key_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
  1025. project_id = "tm_U9Zod13qtsHp"
  1026. project_type = "Gateway"
  1027. ```
  1028. This allows you to run commands against different projects. For example, to listen to the `webhooks` source in the `dev` profile, run:
  1029. ```sh
  1030. hookdeck listen 3030 webhooks -p dev
  1031. ```
  1032. To listen to the `webhooks` source in the `prod` profile, run:
  1033. ```sh
  1034. hookdeck listen 3030 webhooks -p prod
  1035. ```
  1036. ## Global Flags
  1037. The following flags can be used with any command:
  1038. - `--color`: Turn on/off color output (on, off, auto).
  1039. - `--hookdeck-config`: Path to the CLI configuration file. You can also set the `HOOKDECK_CONFIG_FILE` environment variable to the config file path.
  1040. - `--device-name`: A unique name for your device.
  1041. - `--insecure`: Allow invalid TLS certificates.
  1042. - `--log-level`: Set the logging level (debug, info, warn, error).
  1043. - `--profile` or `-p`: Use a specific configuration profile.
  1044. Authentication uses command-specific flags (`hookdeck login --cli-key`, `hookdeck ci --api-key`, or `HOOKDECK_API_KEY`), not global flags.
  1045. There are also hidden flags for development and debugging (not listed in user-facing help); for example `--api-base` sets the API base URL when testing against a local stack:
  1046. * `--api-base`: Sets the API base URL.
  1047. * `--dashboard-base`: Sets the web dashboard base URL.
  1048. * `--console-base`: Deprecated. Guest links now open Hookdeck Inspect; use `--inspect-base`.
  1049. * `--inspect-base`: Sets the Hookdeck Inspect base URL that `listen` links guest accounts to.
  1050. * `--ws-base`: Sets the Websocket base URL.
  1051. ## Troubleshooting
  1052. ### Homebrew: migrating from the third-party tap to homebrew-core
  1053. The stable `hookdeck` formula now lives in [homebrew-core](https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/h/hookdeck.rb). The third-party `hookdeck/hookdeck` tap publishes only the beta formula.
  1054. If you installed via the tap, the move is automatic: `brew update && brew upgrade` will pull the next stable version from homebrew-core. No action needed.
  1055. If you want to switch immediately:
  1056. ```sh
  1057. brew update
  1058. brew upgrade hookdeck
  1059. ```
  1060. ### Homebrew: `hookdeck` and `hookdeck-beta` conflict on link
  1061. Both formulae install a binary called `hookdeck`, so only one can be linked at a time. Switching between them requires `--overwrite`:
  1062. ```sh
  1063. # Switch from beta to stable
  1064. brew link --overwrite hookdeck
  1065. # Switch from stable to beta
  1066. brew link --overwrite hookdeck-beta
  1067. ```
  1068. ### Homebrew: beta install asks for a `brew trust` step
  1069. Once [`HOMEBREW_REQUIRE_TAP_TRUST`](https://docs.brew.sh/Taps) becomes the default in Homebrew 5.2.0 / 6.0.0, installing the beta from the third-party tap requires:
  1070. ```sh
  1071. brew trust --formula hookdeck/hookdeck/hookdeck-beta
  1072. ```
  1073. The stable formula lives in homebrew-core and is unaffected.
  1074. ## Developing
  1075. Running from source:
  1076. ```sh
  1077. go run main.go
  1078. ```
  1079. ### Generating REFERENCE.md
  1080. The [REFERENCE.md](REFERENCE.md) file is generated from Cobra command metadata. After changing commands, flags, or help text, regenerate it in place:
  1081. ```sh
  1082. go run ./tools/generate-reference
  1083. ```
  1084. To validate that REFERENCE.md is up to date (useful in CI):
  1085. ```sh
  1086. go run ./tools/generate-reference --check
  1087. ```
  1088. Build from source by running:
  1089. ```sh
  1090. go build
  1091. ```
  1092. Then run the locally generated `hookdeck-cli` binary:
  1093. ```sh
  1094. ./hookdeck-cli
  1095. ```
  1096. ### Testing the npm package build
  1097. To test the npm package build process locally (including the wrapper script), you can use the automated test script:
  1098. ```sh
  1099. # Run the automated test script (recommended)
  1100. ./test-scripts/test-npm-build.sh
  1101. ```
  1102. The test script will:
  1103. - Build all 6 platform binaries using GoReleaser
  1104. - Verify the binaries directory structure
  1105. - Test the wrapper script on your current platform
  1106. - Verify npm pack includes all required files
  1107. **Manual testing (if you prefer step-by-step):**
  1108. ```sh
  1109. # Install GoReleaser (if not already installed)
  1110. # Option 1: Using Homebrew (recommended on macOS)
  1111. brew install goreleaser
  1112. # Option 2: Download binary from GitHub releases
  1113. # Visit https://github.com/goreleaser/goreleaser/releases/latest
  1114. # Build all platform binaries for npm
  1115. goreleaser build -f .goreleaser/npm.yml --snapshot --clean
  1116. # Verify binaries directory structure
  1117. ls -R binaries/
  1118. # Test the wrapper script on your platform
  1119. node bin/hookdeck.js --version
  1120. # Test npm package creation (dry-run)
  1121. npm pack --dry-run
  1122. ```
  1123. This will create the `binaries/` directory with all 6 platform binaries, allowing you to test the wrapper script locally before publishing.
  1124. ## Testing
  1125. ### Running Acceptance Tests
  1126. The Hookdeck CLI includes comprehensive acceptance tests written in Go. These tests verify end-to-end functionality by executing the CLI and validating outputs.
  1127. **Local testing:**
  1128. ```bash
  1129. # Run all acceptance tests
  1130. go test ./test/acceptance/... -v
  1131. # Run specific test
  1132. go test ./test/acceptance/... -v -run TestCLIBasics
  1133. # Skip acceptance tests (short mode)
  1134. go test ./test/acceptance/... -short
  1135. ```
  1136. **Environment setup:**
  1137. For local testing, create a `.env` file in `test/acceptance/`:
  1138. ```bash
  1139. # test/acceptance/.env
  1140. HOOKDECK_CLI_TESTING_API_KEY=your_api_key_here
  1141. ```
  1142. **CI/CD:**
  1143. In CI environments, set the `HOOKDECK_CLI_TESTING_API_KEY` environment variable directly in your workflow configuration or repository secrets.
  1144. For detailed testing documentation and troubleshooting, see [`test/acceptance/README.md`](test/acceptance/README.md).
  1145. ### Testing npm package and wrapper script
  1146. The npm package includes a wrapper script (`bin/hookdeck.js`) that detects the platform and executes the correct binary.
  1147. **Quick test (using automated script):**
  1148. ```sh
  1149. ./test-scripts/test-npm-build.sh
  1150. ```
  1151. **Manual testing:**
  1152. ```sh
  1153. # Ensure GoReleaser is installed (see "Testing the npm package build" section above)
  1154. # Build all platform binaries
  1155. goreleaser build -f .goreleaser/npm.yml --snapshot --clean
  1156. # Test wrapper script on current platform
  1157. node bin/hookdeck.js version
  1158. # Verify wrapper script can find binary
  1159. node bin/hookdeck.js --help
  1160. # Test npm pack includes all files
  1161. npm pack --dry-run | grep -E "(bin/hookdeck.js|binaries/)"
  1162. ```
  1163. **Note:** The wrapper script expects binaries in `binaries/{platform}-{arch}/hookdeck[.exe]`. When building locally, ensure all platforms are built or the wrapper will fail for missing platforms.
  1164. ### Testing against a local API
  1165. When testing against a non-production Hookdeck API, you can use the
  1166. `--api-base` and `--ws-base` flags, e.g.:
  1167. ```sh
  1168. ./hookdeck-cli --api-base http://localhost:9000 --ws-base ws://localhost:3003 listen 1234
  1169. ```
  1170. Also if running in Docker, the equivalent command would be:
  1171. ```sh
  1172. docker run --rm -it \
  1173. -v $HOME/.config/hookdeck:/root/.config/hookdeck hookdeck/hookdeck-cli \
  1174. --api-base http://host.docker.internal:9000 \
  1175. --ws-base ws://host.docker.internal:3003 \
  1176. listen \
  1177. http://host.docker.internal:1234
  1178. ```
  1179. ### Testing the published npm package
  1180. To verify that the published npm package installs correctly and has the expected layout (wrapper script and platform binaries), use the local test script. It installs into a controlled directory (no global install) and runs the same checks as the `test-npm-install` CI workflow.
  1181. ```sh
  1182. # Test with @latest (default)
  1183. ./test-scripts/test-npm-install-local.sh
  1184. # Test with a specific version or tag
  1185. ./test-scripts/test-npm-install-local.sh 1.7.1
  1186. ./test-scripts/test-npm-install-local.sh @beta
  1187. ```
  1188. Install output is written to `test-scripts/.install-test/` (gitignored).
  1189. ## Releasing
  1190. This section describes the release process for the Hookdeck CLI.
  1191. Maintainers using AI assistants: see **[.agents/skills/hookdeck-cli-release/](.agents/skills/hookdeck-cli-release/)** for the release skill (automation details and release-note workflow).
  1192. ## Release Process
  1193. The release workflow supports tagging from **ANY branch** - it automatically detects which branch contains the tag. This means you can create beta releases directly from feature branches for testing before merging to `main`.
  1194. ### Stable Release (Preferred Method: GitHub UI)
  1195. 1. Ensure all tests pass on `main`
  1196. 2. Go to the [GitHub Releases page](https://github.com/hookdeck/hookdeck-cli/releases)
  1197. 3. Click "Draft a new release"
  1198. 4. Create a new tag with a stable version (e.g., `v1.3.0`)
  1199. 5. Target the `main` branch
  1200. 6. Generate release notes or write them manually
  1201. 7. Publish the release
  1202. The GitHub Actions workflow will automatically:
  1203. - Build binaries for all platforms
  1204. - Create a stable GitHub release
  1205. - Publish to NPM with the `latest` tag
  1206. - Update package managers:
  1207. - Homebrew: stable formula in [homebrew-core](https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/h/hookdeck.rb) is auto-bumped by Homebrew's BrewTestBot (no action from us; runs every ~3 hours after the tag is published). The `hookdeck-beta` formula in our third-party tap is updated only on pre-release tags.
  1208. - Scoop: `hookdeck` package
  1209. - Docker: Updates both the version tag and `latest`
  1210. > **Do not push a bare `git tag`.** Any `v*` tag starts the release pipeline, so a hand-pushed tag
  1211. > publishes to npm, Homebrew, Scoop and Docker from a release with no notes — and npm will not let
  1212. > you republish that version. Always create the release (UI or `gh`), which makes the tag for you.
  1213. > Never use a `v*` tag as a bookmark.
  1214. **Alternative (Command Line):**
  1215. ```bash
  1216. gh release create v1.3.0 --target main --title "v1.3.0" --notes-file notes.md
  1217. ```
  1218. ### Pre-release from Main (General Beta Testing)
  1219. For general beta testing of features that have been merged to `main`:
  1220. **Preferred Method: GitHub UI**
  1221. 1. Ensure `main` branch is in the desired state
  1222. 2. Go to the [GitHub Releases page](https://github.com/hookdeck/hookdeck-cli/releases)
  1223. 3. Click "Draft a new release"
  1224. 4. Create a new tag with pre-release version (e.g., `v1.3.0-beta.1`)
  1225. 5. Target the `main` branch
  1226. 6. Check "Set as a pre-release"
  1227. 7. Publish the release
  1228. 8. GitHub Actions will build and publish with npm tag `beta`
  1229. **Alternative (Command Line):**
  1230. ```bash
  1231. gh release create v1.3.0-beta.1 --target main --prerelease \
  1232. --title "v1.3.0-beta.1" --notes-file notes.md
  1233. ```
  1234. **Installing beta releases:**
  1235. ```sh
  1236. # NPM
  1237. npm install hookdeck-cli@beta -g
  1238. # Homebrew
  1239. brew install hookdeck/hookdeck/hookdeck-beta
  1240. # To force the symlink update and overwrite all conflicting files:
  1241. # brew link --overwrite hookdeck-beta
  1242. # Scoop
  1243. scoop install hookdeck-beta
  1244. # Docker
  1245. docker run hookdeck/hookdeck-cli:v1.3.0-beta.1 version
  1246. ```
  1247. ### Pre-release from Feature Branch (Feature-Specific Testing)
  1248. For testing a specific feature in isolation before merging to main:
  1249. **Preferred Method: GitHub UI**
  1250. 1. Ensure your feature branch is pushed to origin
  1251. 2. Go to the [GitHub Releases page](https://github.com/hookdeck/hookdeck-cli/releases)
  1252. 3. Click "Draft a new release"
  1253. 4. Create a new tag with pre-release version (e.g., `v1.3.0-beta.1`)
  1254. 5. Target your feature branch (e.g., `feat/my-feature`)
  1255. 6. Check "Set as a pre-release"
  1256. 7. Add notes about what's being tested
  1257. 8. Publish the release
  1258. 9. GitHub Actions will automatically detect the branch and build from it
  1259. **Alternative (Command Line):**
  1260. ```bash
  1261. gh release create v1.3.0-beta.1 --target feat/my-feature --prerelease \
  1262. --title "v1.3.0-beta.1" --notes-file notes.md
  1263. ```
  1264. **Installing beta releases:**
  1265. ```sh
  1266. # NPM
  1267. npm install hookdeck-cli@beta -g
  1268. # Homebrew
  1269. brew install hookdeck/hookdeck/hookdeck-beta
  1270. # To force the symlink update and overwrite all conflicting files:
  1271. # brew link --overwrite hookdeck-beta
  1272. # Scoop
  1273. scoop install hookdeck-beta
  1274. # Docker
  1275. docker run hookdeck/hookdeck-cli:v1.3.0-beta.1 version
  1276. ```
  1277. **Note:** Only stable releases (without pre-release identifiers like `-beta`, `-alpha`) will update the `latest` tags across all distribution channels.
  1278. ## Repository Setup
  1279. ### GitHub Repository Settings
  1280. To maintain code quality and protect the main branch, configure the following settings in your GitHub repository:
  1281. **Default Branch:**
  1282. 1. Go to Settings → Branches
  1283. 2. Set default branch to `main` (if not already set)
  1284. **Branch Protection Rules for `main`:**
  1285. 1. Go to Settings → Branches → Branch protection rules
  1286. 2. Add rule for `main` branch
  1287. 3. Enable the following settings:
  1288. - **Require a pull request before merging**
  1289. - Require approvals: 1 (or as needed for your team)
  1290. - **Require status checks to pass before merging**
  1291. - Require branches to be up to date before merging
  1292. - Add status check: `build-linux`, `build-mac`, `build-windows` (from test workflow)
  1293. - **Do not allow bypassing the above settings**
  1294. - **Restrict force pushes** (recommended)
  1295. - **Restrict deletions** (recommended)
  1296. These settings ensure that all changes to `main` go through proper review and testing before being merged.
  1297. ## CLI authentication keys
  1298. Reference for how Hookdeck credentials relate to CLI commands. After any successful login or `hookdeck ci`, the CLI stores a **CLI client key** in your config file as `api_key` (see [Configuration files](#configuration-files)). The same field name is used regardless of how the key was obtained.
  1299. > **The `api_key` field in your config is not a Project API key.** It holds whichever CLI client key the last login produced. The field name is historical, so you cannot tell from the config file alone which kind of credential you have, or what it is allowed to do.
  1300. ### Which key can do what
  1301. | | `hookdeck login`<br>`hookdeck login --cli-key` | `hookdeck ci --api-key` | Project API key<br>(dashboard) |
  1302. |---|---|---|---|
  1303. | What it is | CLI client key, tied to your user | CLI client key, tied to one project | Long-lived key from project settings |
  1304. | Stored in config as `api_key` | Yes | Yes | No — exchanged, never stored |
  1305. | `hookdeck listen`, `hookdeck gateway …` | Yes | Yes | No |
  1306. | `hookdeck project list` / `project use` | **Yes** | **No** — single project, no user | No |
  1307. | Accepted by `hookdeck ci --api-key` | No | No | **Yes** |
  1308. The distinction that catches people out is the middle column: a key from `hookdeck ci` works fine for everyday commands but is pinned to one project, so anything that spans projects fails.
  1309. ### Check which key you have
  1310. `hookdeck whoami` shows the active project but not the key's scope. To tell the two CLI client keys apart, ask for something only a user-associated key can do:
  1311. ```sh
  1312. hookdeck project list
  1313. ```
  1314. - **A list of projects** — you have a user-associated key and can switch projects.
  1315. - **An error saying the credential is scoped to a single project** — you have a project-scoped key from `hookdeck ci`. Run `hookdeck login` (or `hookdeck login --cli-key <key>`) for account-wide access.
  1316. ### CLI client keys (what the CLI runs as)
  1317. A **CLI client key** identifies the Hookdeck CLI to the API (`cli` authentication). It powers `hookdeck listen`, `hookdeck gateway …`, and most other commands after you are configured.
  1318. | How you get it | Typical command | Server check |
  1319. |----------------|-----------------|--------------|
  1320. | Browser or device login | `hookdeck login` | Validate, or poll until fully associated (see below) |
  1321. | Product UI copy-paste | `hookdeck login --cli-key <key>` | Validate (user and project set at creation) |
  1322. | CI / automation | `hookdeck ci --api-key …` | Creates a team-scoped CLI client key (see below) |
  1323. | Guest sandbox | `hookdeck listen` (no prior login) | Guest user and project set at creation |
  1324. Each CLI client key on the server has optional `user_id` and `team_id` fields. There are three association states:
  1325. | State | `user_id` | `team_id` | When |
  1326. |-------|-----------|-----------|------|
  1327. | Pending device login | null | null | Start of `hookdeck login` browser flow, before you finish sign-in |
  1328. | CI / automation | null | set | After `hookdeck ci` (`POST /cli-auth/ci`) |
  1329. | Fully associated | set | set | Dashboard/Console UI keys, guest sandboxes, or after device login completes |
  1330. - **Pending device login** — The CLI polls `GET /cli-auth/poll` until both `user_id` and `team_id` are set. `GET /cli-auth/validate` does not succeed until association is complete.
  1331. - **CI keys** — Scoped to a project (team) but not tied to a user. Validate works immediately; poll requires both fields, so CI keys are configured via validate, not poll.
  1332. - **Fully associated** — User and project are set. Validate works immediately. Keys from dashboard onboarding or Console CLI destination setup are fully associated when created.
  1333. ### Project API key (input to `hookdeck ci` only)
  1334. A **Project API key** is a long-lived key from the Hookdeck dashboard (project settings). It is **not** what the CLI stores in config for day-to-day use. Pass it once to:
  1335. ```sh
  1336. hookdeck ci --api-key $HOOKDECK_API_KEY # or set HOOKDECK_API_KEY
  1337. ```
  1338. The CLI calls `POST /cli-auth/ci` with that Project API key; the server returns a **CLI client key** scoped to that project. That returned key is saved as `api_key` in your config. Use `hookdeck listen` and gateway commands after `hookdeck ci`, not the original Project API key.
  1339. ### Guest credentials
  1340. If you run `hookdeck listen` without an existing profile, the CLI can create a **guest** sandbox (`POST /cli/guest`). The config may include `guest_url` and an `api_key` for that sandbox. `hookdeck login` reuses that existing guest key and waits for the server to upgrade the guest account into a permanent account.
  1341. ### `project list` / `project use`
  1342. Listing and switching projects requires a **user-associated** CLI client key (for example from `hookdeck login` or `hookdeck login --cli-key`). The server returns all projects your user can access. Keys from `hookdeck ci` are scoped to a single project with no user association—they cannot list or switch projects across your account. A Project API key alone is not sufficient either; use interactive login or a product-issued CLI key instead.
  1343. ## License
  1344. Copyright (c) Hookdeck. All rights reserved.
  1345. Licensed under the [Apache License 2.0 license](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.