Skip to content

Say that cli mode needs a binary we do not ship #13

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
garethx merged 1 commit into from
Aug 12, 2026
Merged

Say that cli mode needs a binary we do not ship #13

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,13 +40,23 @@ 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
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
Expand Down
12 changes: 12 additions & 0 deletions docs/operations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading