| FazBrowse GitHub Viewer | Trending | | Home |
| Tools: [Download Repo ZIP] [Original HTTPS Page] |
This release moves the CLI to API version 2026-09-01 and brings delivery groups to the command line: per-group rate limits and overrides on destinations, standalone or inline on a connection, plus a --delivery-group filter across events, request events, metrics, and the MCP tools.
Alongside that is a long list of fixes sharing one shape — the CLI reported success while doing something other than what you asked. listen connected but never said so when its output was piped. gateway metrics accepted filters the endpoint silently ignores and returned unfiltered totals formatted as if filtered. gateway transformation run printed a green tick whether your code worked or threw. hookdeck login opened a browser and hung forever on a machine with no terminal.
Project mode is now project type, following the API. Existing config files keep working in both directions.
Delivery groups on destinations. Rate limits now travel through config.delivery_policy, and you can set per-group limits and overrides directly:
hookdeck gateway destination create --name orders \
--delivery-group-key '$.body.tenant_id' \
--delivery-group-rate 100 --delivery-group-rate-period minute \
--delivery-group-overrides '{"tenant_a": {"rate": 500}}'The same options exist inline when creating a connection, prefixed --destination-delivery-group-*, beside the existing --destination-rate-limit*.
--delivery-group filter on gateway events list, gateway requests list, gateway metrics, and the corresponding MCP tools.
gateway request events gains the full event filter set — --source-id, --destination-id, --connection-id, --status, --attempts, --response-status, --error-code, --issue-id, --body, --headers, --path, --parsed-query, the four date-bound pairs, --order-by and --dir. Previously it offered five flags while the endpoint honoured twenty; the rest were silently dropped.
NO_COLOR is now honoured across the CLI, alongside the existing --color off.
API version 2026-09-01. The cached source-type list is keyed by API version, so upgrading no longer reuses a cache built against 2025-07-01.
listen connects but never prints "Connected". The readiness line was attached to the terminal spinner, so anywhere the spinner could not run — output piped to a file, --color off, no TTY — the CLI connected and forwarded traffic while never confirming it. Reported by a user who concluded the websocket had failed; the tunnel was live the whole time. (#376)
listen looked connected before it was. In the default interactive mode the full UI rendered immediately with a blank status bar, so a connection that was still being established — or had failed — was indistinguishable from a live one. The status bar now always reports state: Connecting…, Connected., or Connection failed: <reason>. (#399)
listen said it gave up but not why. The dial error was debug-only. (#383)
Compact mode printed a bare Listening on with the summary missing. Compact is the automatic fallback when there is no TTY, so this was the line most CI logs carried. (#402)
Terminal hyperlinks were emitted only where they cannot render — escape sequences went into piped and redirected output and were withheld from real terminals, and --color off did not suppress them. (#403)
--color off was ignored by the interactive UI. (#404)
hookdeck login opened a browser and hung indefinitely when there was no terminal. Any CI job, Dockerfile, nohup script or coding agent running it would spawn a browser process and block. It now fails immediately, naming hookdeck ci --api-key, hookdeck login --cli-key and HOOKDECK_API_KEY. The same gap existed on the guest-upgrade path. (#400, #373)
The sign-in URL is now always printed before the spinner. It was previously shown only if launching the browser returned an error — but a browser that fails after launching is undetectable, so on WSL, in containers and under VS Code Remote you got a spinner and no link.
hookdeck login -i with no terminal leaked a raw operation not supported by device. (#401)
Ctrl-C could be dropped during interactive login, leaving the terminal with echo disabled. (#384)
An expired or rejected key now tells you what to do, rather than unexpected http status code: 401, raw response body: Unauthorized.
gateway metrics accepted filters the endpoint ignores. Passing --connection-id to metrics attempts, or --source-id to metrics transformations, was accepted without complaint — but the API silently drops unsupported filters rather than rejecting them, so the CLI printed unfiltered totals formatted exactly like a filtered result. Nothing on screen distinguished the two. Ten such pairs existed on the CLI and 22 on the MCP tools. (#382)
--measures pending only worked if you also passed --granularity. Otherwise it was routed to an endpoint that does not accept the measure and returned a raw 422.
--measures queue_depth never worked. It was advertised in --help but is not a value the endpoint accepts.
--dimensions and --status advertised one shared vocabulary across all four subcommands, and it was wrong on three. Following the help produced a 422. Request events are ACCEPTED/REJECTED, attempts are SUCCESSFUL/FAILED, events carry the full six-value set.
The metrics example in gateway --help was missing the required --measures, so copying it verbatim failed.
--config had its path overwritten on CLI destinations. --config '{"path":"/webhooks"}' created a destination at /, because --cli-path carries a / default and an unset flag beat the value you supplied. (#392)
gateway connection upsert reset an existing CLI destination's path to / on any upsert that omitted --destination-cli-path.
destination update and upsert silently dropped --url (and --cli-path) whenever --type was omitted — which is the normal way to run an update, since the type is already stored. (#406)
Negative rate limits are rejected. --rate-limit -1 was accepted and sent.
Arguments an action does not support are now refused rather than sent and silently dropped by the API.
The metrics tool advertised measures, dimensions and status values that most routes reject. All three are now accurate per action and derived from the same source as the CLI's, so the two cannot drift.
meta.active_project_name was always empty for project-scoped credentials, so a client could only show a bare tm_… id. (#405)
API validation errors surfaced as raw JSON with internal fields, burying the useful message.
ignored_events dropped pagination.
Project mode is now project type, following the API's rename: event_gateway, console, outpost (inbound and outbound both fold into event_gateway). This is internal vocabulary — --output json still emits gateway, outpost, console exactly as before, so scripts reading it need no change.
Config stays compatible in both directions. project_type is written as the display label (Gateway) that v2.5.0 understands, and a type this version does not recognise is preserved rather than blanked.
One caveat, since it is not a config-format property: v2.5.0 reads only team_mode from the auth response and ignores team_type. The two versions coexist because they call different API versions, so the older prefix continues to serve team_mode.
--measures is now a required flag on the metrics subcommands. It was always required by the API; the CLI now says so up front instead of letting the request fail.
Dimensions are validated per metrics route. A dimension the endpoint does not group by is refused with a message naming the ones it does, instead of being sent and rejected.
--config takes precedence over the individual destination config flags, which are ignored when it is present. Set the field in the JSON rather than combining the two. ([#415](https://gith...
Pre-release of v3.0.0: Outpost support, write mode for the Gateway MCP server, and a rename of the Gateway MCP tools.
npm install -g hookdeck-cli@betaEvery Gateway product tool is renamed from hookdeck_* to gateway_*, and the events and requests tools are each split in two. Per-tool permission grants and allowedTools entries do not survive a rename — whatever you had approved for hookdeck_events is not approved for gateway_events, so you will be asked to grant again, and any allowedTools config needs updating by hand.
| Before | After |
|---|---|
| hookdeck_attempts | gateway_attempts |
| hookdeck_connections | gateway_connections |
| hookdeck_destinations | gateway_destinations |
| hookdeck_events | gateway_events (list) and gateway_event (by id) |
| hookdeck_help | gateway_help |
| hookdeck_issues | gateway_issues |
| hookdeck_metrics | gateway_metrics |
| hookdeck_requests | gateway_requests (list) and gateway_request (by id) |
| hookdeck_sources | gateway_sources |
| hookdeck_transformations | gateway_transformations |
hookdeck_login and hookdeck_projects keep their names — they are platform tools shared with the Outpost server.
If you have rules or hooks matching on tool names, prefer a server-scoped pattern such as mcp__hookdeck__* over naming individual tools, so a future rename does not break them again.
Around thirty. Most are cases where a command told you it had done something it had not:
If you have scripts that check exit codes or parse output, this is the release to run them against.
Please report anything you find at https://github.com/hookdeck/hookdeck-cli/issues — a beta is only worth cutting if the problems come back to us.
Full Changelog: v2.5.0...v3.0.0-beta.1
Adds hookdeck outpost mcp, an MCP server giving AI agents access to Outpost, and fixes several things found by driving the previous beta for real.
Still a beta from a feature branch, published for testing before merge. Requires an Outpost project.
hookdeck outpost mcp — 13 tools covering tenants, destinations, destination types, events, attempts, publish, topics, metrics, project config and deployment status, alongside hookdeck_login and hookdeck_projects.
Read-only by default. Write actions are opt-in with --allow-write (or HOOKDECK_MCP_ALLOW_WRITE):
{
"mcpServers": {
"hookdeck-outpost": {
"command": "hookdeck",
"args": ["outpost", "mcp"] // add "--allow-write" to enable changes
}
}
}In read-only mode write actions are absent from the tool schema entirely, so an agent is never offered something it cannot do. --read-only is accepted explicitly and wins if both are passed.
Two reads count as writes, because both hand back a reusable credential: outpost_tenants token mints a tenant JWT, and outpost_tenants portal returns a URL granting portal access.
Publishing needs its own credential. outpost_publish requires a Hookdeck Project API key via --publish-api-key or HOOKDECK_OUTPOST_PUBLISH_API_KEY; without one the tool is not registered. It deliberately does not read HOOKDECK_API_KEY, which elsewhere means "exchange this for CLI credentials" and is commonly exported for CI — publishing sends real events to real destinations and should be something you turned on deliberately.
npm install -g hookdeck-cli@betaFirst beta of Outpost support in the CLI. Adds hookdeck outpost for managing tenants, their destinations, and the events delivered to them — the Outpost equivalent of what hookdeck gateway does for the Event Gateway.
This is a beta from a feature branch, published for real-world testing before merge. It requires an Outpost project; switch with hookdeck project use.
hookdeck outpost — the full command tree:
| Group | Commands |
|---|---|
| tenant | list get upsert delete token portal |
| destination | list get create update delete enable disable |
| destination-type | list get |
| event | list get retry |
| attempt | list get |
| publish | |
| topic | list |
| metrics | events attempts |
| config | get set custom-domain get|set|delete |
| status |
Destination config is passed as key=value pairs, because the fields differ per type and are defined by your Outpost deployment rather than the CLI:
hookdeck outpost tenant upsert acme
hookdeck outpost destination create --tenant-id acme --type webhook \
--config url=https://example.com/hooks --topics user.createdPer-type help. Since --config alone cannot tell you which keys are valid, ask it directly:
hookdeck outpost destination-type get kafka # every field, with constraints
hookdeck outpost destination create --type kafka --help # the same, inlineBoth list each field with whether it is required, whether it is sensitive, and any values or format it accepts — read live from your deployment, so newly added types work without a CLI update.
outpost publish needs a Hookdeck Project API key. It is the one command that does not accept the credentials hookdeck login stores. Pass --api-key or set HOOKDECK_API_KEY:
hookdeck outpost publish --tenant-id acme --topic user.created \
--data '{"user_id":"123"}' --api-key $HOOKDECK_API_KEYEverything above is exercised by automated tests against a real Outpost project, but has not been used in anger. Most valuable feedback:
npm install -g hookdeck-cli@betaOr download a binary from the assets below.
This release makes the CLI safe to run where there is no human: CI, Docker, nohup, and AI agents. Nine fixes, most sharing one failure shape — the CLI would silently do something other than what you asked, and the first symptom was missing traffic rather than an error. hookdeck listen now works headlessly and honours HOOKDECK_API_KEY, --local no longer touches your global config, and empty secrets are rejected instead of quietly producing a source that verifies nothing.
It also ships the guest login improvements merged after v2.4.0.
hookdeck listen reads HOOKDECK_API_KEY. Running the CLI in CI no longer needs a separate hookdeck ci step — export a Project API key and listen exchanges it for CLI credentials, saves them, and connects to your project:
export HOOKDECK_API_KEY="your-project-api-key"
hookdeck listen 3000 shopify ordersPrecedence is --cli-key, then your stored login, then HOOKDECK_API_KEY. An existing login is never repointed by the environment — but a temporary guest profile is, so a machine that once ran listen without credentials still picks up your project when the variable is set. Replacing a guest profile prints a notice with the sandbox URL rather than swapping accounts silently.
hookdeck listen detects when there is no terminal and uses compact output automatically, so it works under CI, Docker, nohup, and coding agents with no flags. Pass --output compact or --output quiet to get the same behaviour on a machine that does have a terminal.
Three of these turn a silent success into a clear failure. Nothing was removed or renamed, but if you have automation that depended on the old behaviour, these are the ones to check.
hookdeck listen no longer dies at startup without a terminal. It defaulted to a full-screen UI that opens /dev/tty; anywhere without one it failed with could not open a new TTY and exited 0 having forwarded nothing — no tunnel, no error, nothing to attribute the failure to. (#333, #339)
hookdeck listen no longer silently creates a guest account when HOOKDECK_API_KEY is set. Events still arrived on your machine, so it looked like it worked — but they went to a throwaway account with no connection, delivery history, retries, or issue triggers, not the project you configured. (#334)
hookdeck ci --local and hookdeck login --local no longer rewrite your global config. --local added a second write rather than redirecting the first, so it silently switched the active project for every other hookdeck command on the machine — the opposite of what the flag is for. (#332)
Empty secret and identity flags are now rejected. An unexported shell variable expands to an empty string, and the CLI accepted it: hookdeck gateway source create --type STRIPE --webhook-secret "$UNSET_VAR" produced a source with no verification at all while looking configured, so it rejected every genuinely signed request. --webhook-secret "", --source-webhook-secret "", --name "" and similar now error with a message naming the likely cause. To clear verification deliberately, use the JSON escape hatch: --config '{"auth": null}'. (#335)
delete and dismiss no longer exit 0 without doing anything. Without a terminal these commands skipped the confirmation prompt, printed Deletion cancelled. and exited 0 — so a CI job deleted nothing and reported success. They now exit non-zero and tell you to pass --force. (#338)
Unauthenticated commands no longer hang for four minutes. Any command run without credentials dropped into interactive sign-in, blocking on a prompt and opening a browser even on a machine with no display. Without a terminal it now exits immediately with instructions for hookdeck ci, HOOKDECK_API_KEY and hookdeck login --cli-key. (#337)
Guest login improvements (merged after v2.4.0): guest credentials are now persisted and attested on login, guest sign-in links refresh while listen runs, and a stale key is preserved rather than discarded when validation returns 401. Note one behaviour change: with a guest profile, hookdeck login now always opens the browser to claim your sandbox instead of short-circuiting on a valid key. To attach the CLI to an existing Hookdeck account, run hookdeck logout then hookdeck login. (#306)
README and hookdeck listen --help now describe running in CI accurately. The previous CI example showed a full-screen UI as the expected output while documenting an environment variable listen ignored — the exact combination the two bugs above disprove.
Full Changelog: v2.4.0...v2.5.0
v2.4.0 makes --cli-key a documented flag on hookdeck listen, saves the key on machines that have no login yet, and fixes it failing when you already have one. It also updates the dependency set and the toolchain used to build releases.
hookdeck listen --cli-key <key> authenticates a single run with a user-scoped CLI key, such as the one shown in the Hookdeck Console. The flag now appears in help output:
$ hookdeck listen --help
--cli-key string Hookdeck CLI key used to authenticate this command, e.g. the key shown in the Hookdeck Console
Anything that reads the CLI's help — your shell's completion, scripts, tooling — can now see it.
Copy a command from the Hookdeck Console:
npx hookdeck-cli listen 3000 my-source --cli-key <key>
If the machine has no stored credential, the key is validated and saved, and later runs no longer need the flag:
Saved CLI key for Sandbox. Future runs won't need --cli-key.
If you already have a login, nothing is written. The key applies to that run only, so a few minutes of forwarding a Console source will not replace the account you were signed in to.
Full Changelog: v2.3.2...v2.4.0
Full Changelog: v2.3.1...v2.3.2
npm users: this is the first 2.3.x release on npm — it includes everything from v2.3.0: copy request payloads in the interactive listen view (C/H/B), MCP list-filter parity for events and requests, and dependency updates.
Full Changelog: v2.3.0...v2.3.1
v2.3.0 adds request-payload copying to the interactive listen view and full list-filter parity for the Event Gateway MCP server's event and request tools, plus dependency updates and documentation improvements.
In the event details view, press:
Off-screen content is included. Works out of the box on macOS and Windows; on Linux/BSD it requires xclip or xsel.
The Event Gateway MCP server's hookdeck_events and hookdeck_requests list tools now support the full set of API list filters (first shipped as v2.3.0-beta.1):
Full Changelog: v2.2.0...v2.3.0
Pre-release of upcoming v2.3.0 — test MCP hookdeck_events and hookdeck_requests list filters before GA.
npm install hookdeck-cli@beta -g
# or: brew install hookdeck/hookdeck/hookdeck-beta| Back | FazBrowse Home | New Git URL |