Summary

First 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.

New features

hookdeck outpost — the full command tree:

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.created

Per-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, inline

Both 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_KEY

What to test

Everything above is exercised by automated tests against a real Outpost project, but has not been used in anger. Most valuable feedback:

• Destination creation across types — webhook is well covered; the AWS, GCP, Azure, RabbitMQ and Kafka types are validated against the schema but have not been created against real infrastructure.
• --config key=value ergonomics. Does it feel right, and is destination-type get a good enough answer to "what fields does this take"?
• The tenant portal and custom domain commands (tenant portal, config custom-domain …) are the least proven surface — they are the four commands with no automated coverage, because they configure a real DNS-verified hostname. Please try them and report anything odd.
• Error messages. They are meant to name the flag that fixes the problem; tell us where they do not.

Known limitations

• Requires an Outpost project. Running these against an Event Gateway project reports the project type and how to switch, rather than failing obscurely.
• outpost publish cannot use hookdeck login credentials, as above.
• MCP support for Outpost is not in this release; it is in progress.

Installing this beta

npm install -g hookdeck-cli@beta

Or download a binary from the assets below.

Summary

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.

New features

• 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 orders

  Precedence 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.

Fixes

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)

Improvements / behavior changes

• 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.

Internal / reliability / infrastructure

• The root --cli-key flag is now hidden, matching --api-key beside it. Authentication is command-specific — hookdeck login --cli-key, hookdeck listen --cli-key, hookdeck ci --api-key — and those remain documented. The global flag still works for anyone already passing it; it is simply no longer advertised as a global option. It was added in #306 and never shipped in a release, so nothing that worked in v2.4.0 changes.
• Dropped go-github v28, whose only use was a single unauthenticated release check and whose only other effect was linking golang.org/x/crypto/openpgp — the unmaintained package flagged by GO-2026-5932, for which no fixed version exists. Replaced with a direct net/http call, which is now covered by tests for the first time. (#331)
• Added a govulncheck job to CI, so a clean scan is enforced rather than asserted once.
• Fixed the release skill's CI gate, which read the legacy commit-status API that GitHub Actions never writes and so reported pending unconditionally, blocking every release. (#336)

Full Changelog: v2.4.0...v2.5.0

Summary

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.

New features

--cli-key is now a documented flag on listen (#329)

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.

listen remembers the key when you have no login (#329)

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.

Fixes

• --cli-key no longer fails when you already have a login (#329). The supplied key was sent alongside the project id from your previous login. They belong to different projects, so every call failed with your API key is invalid or expired, with nothing to indicate why. The key's own project is now resolved and used for that run.
• An empty --cli-key fails immediately (#329). --cli-key= reached the API and came back as an authentication error, which described neither the problem nor the fix. It now fails locally: --cli-key needs a value.

Security

• golang.org/x/crypto updated to v0.52.0 (#330) — resolves 13 advisories (7 critical, 2 high, 4 moderate). The package is an indirect dependency that the CLI does not import directly, so exposure was limited.
• Release binaries now build with Go 1.26.5 (#330), up from 1.24.9. The previous toolchain carried standard library advisories reachable from this code in crypto/x509, crypto/tls, net/http and net/textproto. Scanning the same tree under both: 10 findings before, 1 after.

Internal

• Releases are gated on the acceptance suite via a reusable workflow (#328)
• Unit tests and builds now run on push to main (#325)
• Fixed a telemetry test flake caused by proxy state carrying across 502 retries (#327)
• Added KNOWN_ISSUES.md, starting with listen session expiry (#324)

Full Changelog: v2.3.2...v2.4.0

Fixes

• hookdeck listen now recovers automatically when its server-side session expires (for example after your machine has been asleep or offline for a while). Previously the CLI could appear connected while every event failed with CLI_UNAVAILABLE, requiring a manual restart. Routine reconnects (deploys, session turnover) are now quiet instead of logging alarming errors, and pressing Ctrl+C closes the connection cleanly so the server releases your session immediately. (#322)
• Dashboard deep-links now include the correct team_id when using a user-scoped CLI key. The "View dashboard" link and the open-in-dashboard (o) action previously produced links with an empty team_id=; they now resolve the active project (falling back to the connections' team). (#320)
• hookdeck whoami now reports the active project from your configuration instead of the team bound to the CLI key. (#319)

Full Changelog: v2.3.1...v2.3.2

Fixes

• Fix npm publishing (#316). v2.3.0 published to GitHub, Homebrew, Scoop, and Docker, but its npm publish job failed (Node 20 could no longer install npm@latest, which now requires Node ≥ 22.22). v2.3.1 runs that job on Node 22 and publishes to npm. No CLI code changes since v2.3.0.

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

Summary

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.

New features

Copy request payloads from the interactive listen view (#313)

In the event details view, press:

• C — copy the complete request (request line, headers, and body)
• H — copy just the request headers
• B — copy just the request body

Off-screen content is included. Works out of the box on macOS and Windows; on Linux/BSD it requires xclip or xsel.

MCP list-filter parity for events and requests (#301)

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):

• Payload search: body, headers, parsed_query, path (JSON object or string)
• Date windows: *_after / *_before with ISO 8601 — e.g. created_after, last_attempt_after, ingested_after
• Events: id, attempts, cli_id, successful_after/before, last_attempt_after/before
• Requests: id, created_after/before, ingested_after/before, order_by, dir
• Parameter docs via hookdeck_help topics hookdeck_events / hookdeck_requests

Improvements

• Authenticate listen with a key directly: documented that hookdeck listen accepts --cli-key <user-scoped CLI key> or --api-key <project key> to authenticate a single run without a prior hookdeck login (the flags already worked but were hidden). Verified end-to-end.
• Clearer errors for project-scoped keys (#308): project list and project use now fail fast with an explanation when used with a CI/project-scoped key that cannot span projects.

Dependencies

• Bump github.com/modelcontextprotocol/go-sdk 1.6.1 → 1.7.0 (#312)
• Bump golang.org/x/term 0.43.0 → 0.45.0 (#311)
• Bump golang.org/x/sys 0.45.0 → 0.47.0 (#310)

Internal / docs

• Name the Event Gateway product correctly in the listen docs
• Clarify multi-source support in listen help text (#303)
• Promote homebrew-core as the primary macOS install path (#299)
• Remove the non-functional issue-auto-implement CI automation (#304)

Full Changelog: v2.2.0...v2.3.0

Beta: MCP list filter parity

Pre-release of upcoming v2.3.0 — test MCP hookdeck_events and hookdeck_requests list filters before GA.

What to test

• Payload search: body, headers, parsed_query, path on list (JSON object or string)
• Date windows: *_after / *_before with ISO 8601 (e.g. created_after, last_attempt_after, ingested_after) — do not pass field[gte] in MCP args
• Events: id, attempts, cli_id, successful_after/before, last_attempt_after/before
• Requests: id, created_after/before, ingested_after/before, order_by, dir
• hookdeck_help topics hookdeck_events / hookdeck_requests for parameter docs

Install (beta)

npm install hookdeck-cli@beta -g
# or: brew install hookdeck/hookdeck/hookdeck-beta

Full Changelog (vs v2.2.0)

v2.2.0...v2.3.0-beta.1

Summary

GA release that promotes the v2.1.2-beta.1 auth-recovery work to stable, standardises shell-completion output to align with other Cobra CLIs (small breaking change), and lands homebrew-core submission prep.

Breaking Changes / Migration

• hookdeck completion --shell <shell> now writes the completion script to standard output
  • Reason: aligns with every other major Cobra-based CLI (gh, goreleaser, kubectl, helm, terraform) and enables idiomatic Homebrew/Scoop install patterns. The previous behaviour (writing hookdeck-completion.bash/.zsh to the current directory and printing setup instructions) was non-standard.
  • Affected users: anyone running hookdeck completion manually and relying on the generated file or the printed instructions. Users installing via Homebrew or Scoop are unaffected — completions install automatically.
  • Update scripts: redirect the output instead of expecting a file. For example:

    # Source for the current session
    source <(hookdeck completion --shell bash)
    source <(hookdeck completion --shell zsh)
    
    # Install permanently
    hookdeck completion --shell bash > /usr/local/etc/bash_completion.d/hookdeck
    hookdeck completion --shell zsh > "${fpath[1]}/_hookdeck"

    See hookdeck completion --help for full guidance.

Fixes

• Auth recovery for stale keys, clearer 401 UX (#286): clearer error messages when stored credentials become invalid; hookdeck login and hookdeck whoami provide better recovery guidance; quieter logging for expected validate-401s; the MCP hookdeck_login tool returns consistent recovery copy.

Internal

• CGO disabled for macOS builds in GoReleaser config — the codebase is pure Go; the flag was vestigial (#296).
• REFERENCE.md regenerated to document the gateway connection pause/unpause argument as ID or name (#296).
• Preparation for hookdeck homebrew-core submission (#295, #296).
• Dependency bumps: golang.org/x/sys, golang.org/x/term, github.com/modelcontextprotocol/go-sdk (#284, #285, #287, #291, #292, #293).

Full Changelog: v2.1.1...v2.2.0

Beta (pre-release)

Pre-release build from PR #286. Please validate auth and login flows before we ship a stable patch.

Fixes and improvements

• Clearer messaging when the API rejects credentials — HTTP 401 responses surface a short, actionable message. For hookdeck gateway mcp, that text is written to stderr so JSON-RPC on stdout stays clean for MCP clients.
• Less noisy logs for expected auth failures — 401 responses are logged at debug instead of error by default (use --log-level debug when diagnosing HTTP).
• hookdeck login with an invalid saved key — if validate rejects the stored key, the CLI prints that the key is no longer valid and continues into the usual browser/device sign-in flow (you do not need hookdeck logout first).
• In-process client refresh — after a successful browser login, RefreshCachedAPIClient() syncs the cached *hookdeck.Client from the updated profile.

Install

After the release workflow finishes, install the beta per README — Releasing / beta (for example npm install hookdeck-cli@beta -g, Homebrew hookdeck-beta, etc.).

Full Changelog: v2.1.1...v2.1.2-beta.1

Summary

Patch release focused on gateway MCP reliability when authenticating, cleaner stdio behavior for MCP, and login / API-key validation fixes. Also includes internal telemetry metadata and minor maintainer documentation already on main since v2.1.0.

Fixes

• Gateway MCP (#280): Auth-aware MCP server behavior, stderr usage for MCP execution paths, and login / reauth flow improvements so agents get clearer results when not logged in.
• API key validation: Validate keys without sending stale team/project headers; keep the local profile aligned with the API response after login.

Internal

• Telemetry: For API requests that include X-Hookdeck-CLI-Telemetry, the JSON may now include command_flags: the names of flags you explicitly passed on the command line (not values). Telemetry remains optional; use hookdeck telemetry disabled or HOOKDECK_CLI_TELEMETRY_DISABLED to opt out.

Full Changelog: v2.1.0...v2.1.1