From 41270168a3a2d28f02322acbd7cf731971c11d8c Mon Sep 17 00:00:00 2001 From: garethx Date: Wed, 12 Aug 2026 13:09:45 +0100 Subject: [PATCH] Say that cli mode needs a binary we do not ship MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The default mode depends on the Hookdeck CLI, and Install never mentioned it. The only reference anywhere in the README was a line in Connection modes describing what the CLI does, not how to get it — so a reader could follow every documented step, have a correct configuration, and still have a gateway that refuses to start. It is not bundled and pip cannot install it: it is a separate Go binary. Also records that no `hookdeck login` is needed. That was true when the README was written and stopped being true when the gateway started authenticating a CLI session of its own from the API key — which is worth stating positively, since "log in first" is the reasonable assumption and doing it by hand is how the two projects drift apart. `doctor` already catches all of this. It should not be the first place a reader learns it. Co-Authored-By: Claude Opus 5 --- README.md | 10 ++++++++++ docs/operations.md | 12 ++++++++++++ 2 files changed, 22 insertions(+) diff --git a/README.md b/README.md index 07f4566..bd33c9b 100644 --- a/README.md +++ b/README.md @@ -40,6 +40,14 @@ export HOOKDECK_EG_API_KEY=... # provisions connections export HOOKDECK_EG_WEBHOOK_SECRET=... # verifies deliveries ``` +CLI mode is the default, and it needs the [Hookdeck CLI](https://hookdeck.com/docs/cli) — a separate binary, not bundled with this plugin and not installed by pip: + +```bash +brew install hookdeck/hookdeck/hookdeck # or: npm install -g hookdeck-cli +``` + +You do not need to run `hookdeck login`. The gateway authenticates a CLI session of its own from `HOOKDECK_EG_API_KEY` and keeps it in `~/.hermes/hookdeck/`, so it never touches a session you use for other work — and cannot end up forwarding from a different project than the one it provisions. [Push mode](docs/operations.md) needs no CLI at all. + Then create a route and check the setup: ```bash @@ -47,6 +55,8 @@ hermes hookdeck setup my-route hermes hookdeck doctor ``` +`doctor` is the check that everything above landed: it reports a missing or too-old CLI, a secret that is not set, and a CLI pointed at the wrong project. + A [free Hookdeck account](https://dashboard.hookdeck.com/signup) is enough for development and small production workloads. ## How it works diff --git a/docs/operations.md b/docs/operations.md index a358274..8fe1a23 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -10,6 +10,18 @@ The default. The Hookdeck CLI holds an outbound connection and forwards events to a loopback listener, so a laptop or a homelab box behind NAT works without ngrok or a VPS. +The CLI is a separate binary — `brew install hookdeck/hookdeck/hookdeck`, or +`npm install -g hookdeck-cli`. It is not bundled with this plugin and pip does +not install it, so a gateway that has everything else right still refuses to +start in `cli` mode without it: + +``` +✗ Hookdeck CLI 'hookdeck' not found — install it, set + platforms.hookdeck.extra.cli_binary, or switch to mode: push +``` + +`hermes hookdeck doctor` reports the same thing before you get that far. + **A CLI destination is not a durable buffer.** With no listener attached, events become `CLI_DISCONNECTED` ignored events and the request is discarded — not queued, not retried. An *abnormal* disconnect gets a short server-side