hookdeck-cli 1.0.4 → 1.2.0-beta.1

package/README.md

@@ -14,7 +14,8 @@ Hookdeck for development is completely free, and we monetize the platform with o
 
 For a complete reference, see the [CLI reference](https://hookdeck.com/docs/cli?ref=github-hookdeck-cli).
 
-https://github.com/user-attachments/assets/5fca7842-9c41-411c-8cd6-2f32f84fa907
+https://github.com/user-attachments/assets/7a333c5b-e4cb-45bb-8570-29fafd137bd2
+
 
 ## Installation
 
@@ -28,6 +29,12 @@ Hookdeck CLI is distributed as an NPM package:
 npm install hookdeck-cli -g
 ```
 
+To install a beta (pre-release) version:
+
+```sh
+npm install hookdeck-cli@beta -g
+```
+
 ### macOS
 
 Hookdeck CLI is available on macOS via [Homebrew](https://brew.sh/):
@@ -36,6 +43,12 @@ Hookdeck CLI is available on macOS via [Homebrew](https://brew.sh/):
 brew install hookdeck/hookdeck/hookdeck
 ```
 
+To install a beta (pre-release) version:
+
+```sh
+brew install hookdeck/hookdeck/hookdeck-beta
+```
+
 ### Windows
 
 Hookdeck CLI is available on Windows via the [Scoop](https://scoop.sh/) package manager:
@@ -45,6 +58,12 @@ scoop bucket add hookdeck https://github.com/hookdeck/scoop-hookdeck-cli.git
 scoop install hookdeck
 ```
 
+To install a beta (pre-release) version:
+
+```sh
+scoop install hookdeck-beta
+```
+
 ### Linux Or without package managers
 
 To install the Hookdeck CLI on Linux without a package manager:
@@ -53,6 +72,8 @@ To install the Hookdeck CLI on Linux without a package manager:
 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).
@@ -62,6 +83,14 @@ 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:
+
+```sh
+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:
 
@@ -99,6 +128,7 @@ hookdeck login
 ```
 
 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:
+
 ```sh
 hookdeck login --interactive
 ```
@@ -110,17 +140,52 @@ hookdeck login --interactive
 Start a session to forward your events to an HTTP server.
 
 ```sh
-hookdeck listen <port-or-URL> <source-alias?> <connection-query?> [--path?]
+hookdeck listen <port-or-URL> <source-alias?> <connection-query?> [flags]
+
+Flags:
+  --path string             Sets the path to which events are forwarded (e.g., /webhooks or /api/stripe)
+  --output string           Output mode: interactive (full UI), compact (simple logs), quiet (only fatal errors) (default "interactive")
+  --max-connections int     Maximum concurrent connections to local endpoint (default: 50, increase for high-volume testing)
+  --filter-body string      Filter events by request body using Hookdeck filter syntax (JSON)
+  --filter-headers string   Filter events by request headers using Hookdeck filter syntax (JSON)
+  --filter-query string     Filter events by query parameters using Hookdeck filter syntax (JSON)
+  --filter-path string      Filter events by request path using Hookdeck filter syntax (JSON)
 ```
 
 Hookdeck works by routing events received for a given `source` (i.e., Shopify, Github, etc.) to its defined `destination` by connecting them with a `connection` to a `destination`. The CLI allows you to receive events for any given connection and forward them to your localhost at the specified port or any valid URL.
 
 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.
 
-Contrary to ngrok, **Hookdeck does not allow to append a path to your event URL**. Instead, the routing is done within Hookdeck configuration. This means you will also be prompted to specify your `destination` path, and you can have as many as you want per `source`.
-
 > 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.
 
+#### Interactive Mode
+
+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:
+
+- **Connection Header**: Shows your sources, webhook URLs, and connection routing
+  - Auto-collapses when the first event arrives to save space
+  - Toggle with `i` to expand/collapse connection details
+- **Event List**: Scrollable history of all received events (up to 1000 events)
+  - Auto-scrolls to show latest events as they arrive
+  - Manual navigation pauses auto-scrolling
+- **Status Bar**: Shows event details and available keyboard shortcuts
+- **Event Details View**: Full request/response inspection with headers and body
+
+#### Interactive Keyboard Shortcuts
+
+While in interactive mode, you can use the following keyboard shortcuts:
+
+- `↑` / `↓` or `k` / `j` - Navigate between events (select different events)
+- `i` - Toggle connection information (expand/collapse connection details)
+- `r` - Retry the selected event
+- `o` - Open the selected event in the Hookdeck dashboard
+- `d` - Show detailed request/response information for the selected event (press `d` or `ESC` to close)
+  - When details view is open: `↑` / `↓` scroll through content, `PgUp` / `PgDown` for page navigation
+- `q` - Quit the application (terminal state is restored)
+- `Ctrl+C` - Also quits the application
+
+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.
+
 #### Listen to all your connections for a given source
 
 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.
@@ -128,18 +193,24 @@ The second param, `source-alias` is used to select a specific source to listen o
 ```sh
 $ hookdeck listen 3000 shopify
 
-👉  Inspect and replay events: https://dashboard.hookdeck.com/cli/events
+●── HOOKDECK CLI ──●
+
+Listening on 1 source • 2 connections • [i] Collapse
 
 Shopify Source
-🔌 Event URL: https://events.hookdeck.com/e/src_DAjaFWyyZXsFdZrTOKpuHnOH
+│  Requests to → https://events.hookdeck.com/e/src_DAjaFWyyZXsFdZrTOKpuHnOH
+├─ Forwards to → http://localhost:3000/webhooks/shopify/inventory (Inventory Service)
+└─ Forwards to → http://localhost:3000/webhooks/shopify/orders (Orders Service)
 
-Connections
-Inventory Service forwarding to /webhooks/shopify/inventory
-Orders Service forwarding to /webhooks/shopify/orders
+💡 Open dashboard to inspect, retry & bookmark events: https://dashboard.hookdeck.com/events/cli?team_id=...
 
+Events • [↑↓] Navigate ──────────────────────────────────────────────────────────
 
-⣾ Getting ready...
+2025-10-12 14:32:15 [200] POST http://localhost:3000/webhooks/shopify/orders (23ms) → https://dashboard.hookdeck.com/events/evt_...
+> 2025-10-12 14:32:18 [200] POST http://localhost:3000/webhooks/shopify/inventory (45ms) → https://dashboard.hookdeck.com/events/evt_...
 
+───────────────────────────────────────────────────────────────────────────────
+> ✓ Last event succeeded with status 200 | [r] Retry • [o] Open in dashboard • [d] Show data
 ```
 
 #### Listen to multiple sources
@@ -149,20 +220,32 @@ Orders Service forwarding to /webhooks/shopify/orders
 ```sh
 $ hookdeck listen 3000 '*'
 
-👉  Inspect and replay events: https://dashboard.hookdeck.com/cli/events
+●── HOOKDECK CLI ──●
+
+Listening on 3 sources • 3 connections • [i] Collapse
+
+stripe
+│  Requests to → https://events.hookdeck.com/e/src_DAjaFWyyZXsFdZrTOKpuHn01
+└─ Forwards to → http://localhost:3000/webhooks/stripe (cli-stripe)
 
-Sources
-🔌 stripe URL: https://events.hookdeck.com/e/src_DAjaFWyyZXsFdZrTOKpuHn01
-🔌 shopify URL: https://events.hookdeck.com/e/src_DAjaFWyyZXsFdZrTOKpuHn02
-🔌 twilio URL: https://events.hookdeck.com/e/src_DAjaFWyyZXsFdZrTOKpuHn03
+shopify
+│  Requests to → https://events.hookdeck.com/e/src_DAjaFWyyZXsFdZrTOKpuHn02
+└─ Forwards to → http://localhost:3000/webhooks/shopify (cli-shopify)
 
-Connections
-stripe -> cli-stripe forwarding to /webhooks/stripe
-shopify -> cli-shopify forwarding to /webhooks/shopify
-twilio -> cli-twilio forwarding to /webhooks/twilio
+twilio
+│  Requests to → https://events.hookdeck.com/e/src_DAjaFWyyZXsFdZrTOKpuHn03
+└─ Forwards to → http://localhost:3000/webhooks/twilio (cli-twilio)
 
-⣾ Getting ready...
+💡 Open dashboard to inspect, retry & bookmark events: https://dashboard.hookdeck.com/events/cli?team_id=...
 
+Events • [↑↓] Navigate ──────────────────────────────────────────────────────────
+
+2025-10-12 14:35:21 [200] POST http://localhost:3000/webhooks/stripe (12ms) → https://dashboard.hookdeck.com/events/evt_...
+2025-10-12 14:35:44 [200] POST http://localhost:3000/webhooks/shopify (31ms) → https://dashboard.hookdeck.com/events/evt_...
+> 2025-10-12 14:35:52 [200] POST http://localhost:3000/webhooks/twilio (18ms) → https://dashboard.hookdeck.com/events/evt_...
+
+───────────────────────────────────────────────────────────────────────────────
+> ✓ Last event succeeded with status 200 | [r] Retry • [o] Open in dashboard • [d] Show data
 ```
 
 #### Listen to a subset of connections
@@ -172,17 +255,22 @@ The 3rd param, `connection-query` specifies which connection with a CLI destinat
 ```sh
 $ hookdeck listen 3000 shopify orders
 
-👉  Inspect and replay events: https://dashboard.hookdeck.com/cli/events
+●── HOOKDECK CLI ──●
+
+Listening on 1 source • 1 connection • [i] Collapse
 
 Shopify Source
-🔌 Event URL: https://events.hookdeck.com/e/src_DAjaFWyyZXsFdZrTOKpuHnOH
+│  Requests to → https://events.hookdeck.com/e/src_DAjaFWyyZXsFdZrTOKpuHnOH
+└─ Forwards to → http://localhost:3000/webhooks/shopify/orders (Orders Service)
 
-Connections
-Orders Service forwarding to /webhooks/shopify/orders
+💡 Open dashboard to inspect, retry & bookmark events: https://dashboard.hookdeck.com/events/cli?team_id=...
 
+Events • [↑↓] Navigate ──────────────────────────────────────────────────────────
 
-⣾ Getting ready...
+> 2025-10-12 14:38:09 [200] POST http://localhost:3000/webhooks/shopify/orders (27ms) → https://dashboard.hookdeck.com/events/evt_...
 
+───────────────────────────────────────────────────────────────────────────────
+> ✓ Last event succeeded with status 200 | [r] Retry • [o] Open in dashboard • [d] Show data
 ```
 
 #### Changing the path events are forwarded to
@@ -192,19 +280,104 @@ The `--path` flag sets the path to which events are forwarded.
 ```sh
 $ hookdeck listen 3000 shopify orders --path /events/shopify/orders
 
-👉  Inspect and replay events: https://dashboard.hookdeck.com/cli/events
+●── HOOKDECK CLI ──●
+
+Listening on 1 source • 1 connection • [i] Collapse
 
 Shopify Source
-🔌 Event URL: https://events.hookdeck.com/e/src_DAjaFWyyZXsFdZrTOKpuHnOH
+│  Requests to → https://events.hookdeck.com/e/src_DAjaFWyyZXsFdZrTOKpuHnOH
+└─ Forwards to → http://localhost:3000/events/shopify/orders (Orders Service)
+
+💡 Open dashboard to inspect, retry & bookmark events: https://dashboard.hookdeck.com/events/cli?team_id=...
+
+Events • [↑↓] Navigate ──────────────────────────────────────────────────────────
 
-Connections
-Orders Service forwarding to /events/shopify/orders
+> 2025-10-12 14:40:23 [200] POST http://localhost:3000/events/shopify/orders (19ms) → https://dashboard.hookdeck.com/events/evt_...
 
+───────────────────────────────────────────────────────────────────────────────
+> ✓ Last event succeeded with status 200 | [r] Retry • [o] Open in dashboard • [d] Show data
+```
+
+#### Controlling output verbosity
+
+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.
+
+**Available modes:**
+
+- `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.
+- `compact` - Simple one-line logs for all events without interactive features. Events are appended to your terminal history.
+- `quiet` - Only displays fatal connection errors (network failures, timeouts), not HTTP errors
+
+All modes display connection information at startup and a connection status message.
 
-⣾ Getting ready...
+**Examples:**
 
+```sh
+# Default - full interactive UI with keyboard shortcuts
+$ hookdeck listen 3000 shopify
+
+# Simple logging mode - prints all events as one-line logs
+$ hookdeck listen 3000 shopify --output compact
+
+# Quiet mode - only shows fatal connection errors
+$ hookdeck listen 3000 shopify --output quiet
 ```
 
+**Compact mode output:**
+
+```
+Listening on
+shopify
+└─ Forwards to → http://localhost:3000
+
+Connected. Waiting for events...
+
+2025-10-08 15:56:53 [200] POST http://localhost:3000 (45ms) → https://...
+2025-10-08 15:56:54 [422] POST http://localhost:3000 (12ms) → https://...
+```
+
+**Quiet mode output:**
+
+```
+Listening on
+shopify
+└─ Forwards to → http://localhost:3000
+
+Connected. Waiting for events...
+
+2025-10-08 15:56:53 [ERROR] Failed to POST: connection refused
+```
+
+> 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.
+
+#### Filtering events
+
+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.
+
+**Filter flags:**
+
+- `--filter-body` - Filter events by request body content (JSON)
+- `--filter-headers` - Filter events by request headers (JSON)
+- `--filter-query` - Filter events by query parameters (JSON)
+- `--filter-path` - Filter events by request path (JSON)
+
+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.
+
+**Examples:**
+
+```sh
+# Filter events by body content (only events with matching data)
+hookdeck listen 3000 github --filter-body '{"action": "opened"}'
+
+# Filter events with multiple conditions
+hookdeck listen 3000 stripe --filter-body '{"type": "charge.succeeded"}' --filter-headers '{"x-stripe-signature": {"$exist": true}}'
+
+# Filter using operators
+hookdeck listen 3000 api --filter-body '{"amount": {"$gte": 100}}'
+```
+
+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.
+
 #### Viewing and interacting with your events
 
 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.
@@ -226,6 +399,7 @@ For local development scenarios, you can instruct the `listen` command to bypass
 **This is dangerous and should only be used in trusted local development environments for destinations you control.**
 
 Example of skipping SSL validation for an HTTPS destination:
+
 ```sh
 hookdeck listen --insecure https://<your-ssl-url-or-url:port>/ <source-alias?> <connection-query?>
 ```
@@ -256,17 +430,43 @@ Done! The Hookdeck CLI is configured in project MyProject
 
 $ hookdeck listen 3000 shopify orders
 
-👉  Inspect and replay events: https://dashboard.hookdeck.com/cli/events
+●── HOOKDECK CLI ──●
+
+Listening on 1 source • 1 connection • [i] Collapse
 
 Shopify Source
-🔌 Event URL: https://events.hookdeck.com/e/src_DAjaFWyyZXsFdZrTOKpuHnOH
+│  Requests to → https://events.hookdeck.com/e/src_DAjaFWyyZXsFdZrTOKpuHnOH
+└─ Forwards to → http://localhost:3000/webhooks/shopify/orders (Orders Service)
+
+💡 Open dashboard to inspect, retry & bookmark events: https://dashboard.hookdeck.com/events/cli?team_id=...
+
+Events • [↑↓] Navigate ──────────────────────────────────────────────────────────
 
-Connections
-Inventory Service forwarding to /webhooks/shopify/inventory
+> 2025-10-12 14:42:55 [200] POST http://localhost:3000/webhooks/shopify/orders (34ms) → https://dashboard.hookdeck.com/events/evt_...
 
+───────────────────────────────────────────────────────────────────────────────
+> ✓ Last event succeeded with status 200 | [r] Retry • [o] Open in dashboard • [d] Show data
+```
+
+### Manage connections
 
-⣾ Getting ready...
+Create and manage webhook connections between sources and destinations with inline resource creation, authentication, processing rules, and lifecycle management. For detailed examples with authentication, filters, retry rules, and rate limiting, see the complete [connection management](#manage-connections) section below.
 
+```sh
+hookdeck connection [command]
+
+# Available commands
+hookdeck connection list      # List all connections
+hookdeck connection get       # Get connection details
+hookdeck connection create    # Create a new connection
+hookdeck connection upsert    # Create or update a connection (idempotent)
+hookdeck connection delete    # Delete a connection
+hookdeck connection enable    # Enable a connection
+hookdeck connection disable   # Disable a connection
+hookdeck connection pause     # Pause a connection
+hookdeck connection unpause   # Unpause a connection
+hookdeck connection archive   # Archive a connection
+hookdeck connection unarchive # Unarchive a connection
 ```
 
 ### Manage active project
@@ -296,42 +496,303 @@ hookdeck project use [<organization_name> [<project_name>]]
 
 **Behavior:**
 
--   **`hookdeck project use`** (no arguments):
-    An interactive prompt will guide you through selecting your organization and then the project within that organization.
-    ```sh
-    $ hookdeck project use
-    Use the arrow keys to navigate: ↓ ↑ → ←
-    ? Select Organization:
-        My Org
-      ▸ Another Org
-    ...
-    ? Select Project (Another Org):
-        Project X
-      ▸ Project Y
-    Selecting project Project Y
-    Successfully set active project to: [Another Org] Project Y
-    ```
-
--   **`hookdeck project use <organization_name>`** (one argument):
-    Filters projects by the specified `<organization_name>`.
-    - If multiple projects exist under that organization, you'll be prompted to choose one.
-    - If only one project exists, it will be selected automatically.
-    ```sh
-    $ hookdeck project use "My Org"
-    # (If multiple projects, prompts to select. If one, auto-selects)
-    Successfully set active project to: [My Org] Default Project
-    ```
-
--   **`hookdeck project use <organization_name> <project_name>`** (two arguments):
-    Directly selects the project `<project_name>` under the organization `<organization_name>`.
-    ```sh
-    $ hookdeck project use "My Corp" "API Staging"
-    Successfully set active project to: [My Corp] API Staging
-    ```
+- **`hookdeck project use`** (no arguments):
+  An interactive prompt will guide you through selecting your organization and then the project within that organization.
+
+  ```sh
+  $ hookdeck project use
+  Use the arrow keys to navigate: ↓ ↑ → ←
+  ? Select Organization:
+      My Org
+    ▸ Another Org
+  ...
+  ? Select Project (Another Org):
+      Project X
+    ▸ Project Y
+  Selecting project Project Y
+  Successfully set active project to: [Another Org] Project Y
+  ```
+
+- **`hookdeck project use <organization_name>`** (one argument):
+  Filters projects by the specified `<organization_name>`.
+
+  - If multiple projects exist under that organization, you'll be prompted to choose one.
+  - If only one project exists, it will be selected automatically.
+
+  ```sh
+  $ hookdeck project use "My Org"
+  # (If multiple projects, prompts to select. If one, auto-selects)
+  Successfully set active project to: [My Org] Default Project
+  ```
+
+- **`hookdeck project use <organization_name> <project_name>`** (two arguments):
+  Directly selects the project `<project_name>` under the organization `<organization_name>`.
+  ```sh
+  $ hookdeck project use "My Corp" "API Staging"
+  Successfully set active project to: [My Corp] API Staging
+  ```
 
 Upon successful selection, you will generally see a confirmation message like:
 `Successfully set active project to: [<organization_name>] <project_name>`
 
+### Manage connections
+
+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.
+
+#### Create a connection
+
+Create a new connection between a source and destination. You can create the source and destination inline or reference existing resources:
+
+```sh
+# Basic connection with inline source and destination
+$ hookdeck connection create \
+  --source-name "github-repo" \
+  --source-type GITHUB \
+  --destination-name "ci-system" \
+  --destination-type HTTP \
+  --destination-url "https://api.example.com/webhooks"
+
+✔ Connection created successfully
+Connection: github-repo-to-ci-system (conn_abc123)
+Source: github-repo (src_xyz789)
+Source URL: https://hkdk.events/src_xyz789
+Destination: ci-system (dst_def456)
+
+# Using existing source and destination
+$ hookdeck connection create \
+  --source "existing-source-name" \
+  --destination "existing-dest-name" \
+  --name "new-connection" \
+  --description "Connects existing resources"
+```
+
+#### Add source authentication
+
+Verify webhooks from providers like Stripe, GitHub, or Shopify by adding source authentication:
+
+```sh
+# Stripe webhook signature verification
+$ hookdeck connection create \
+  --source-name "stripe-prod" \
+  --source-type STRIPE \
+  --source-webhook-secret "whsec_abc123xyz" \
+  --destination-name "payment-api" \
+  --destination-type HTTP \
+  --destination-url "https://api.example.com/webhooks/stripe"
+
+# GitHub webhook signature verification
+$ hookdeck connection create \
+  --source-name "github-webhooks" \
+  --source-type GITHUB \
+  --source-webhook-secret "ghp_secret123" \
+  --destination-name "ci-system" \
+  --destination-type HTTP \
+  --destination-url "https://ci.example.com/webhook"
+```
+
+#### Add destination authentication
+
+Secure your destination endpoint with bearer tokens, API keys, or basic authentication:
+
+```sh
+# Destination with bearer token
+$ hookdeck connection create \
+  --source-name "webhook-source" \
+  --source-type HTTP \
+  --destination-name "secure-api" \
+  --destination-type HTTP \
+  --destination-url "https://api.example.com/webhooks" \
+  --destination-bearer-token "bearer_token_xyz"
+
+# Destination with API key
+$ hookdeck connection create \
+  --source-name "webhook-source" \
+  --source-type HTTP \
+  --destination-name "api-endpoint" \
+  --destination-type HTTP \
+  --destination-url "https://api.example.com/webhooks" \
+  --destination-api-key "your_api_key"
+
+# Destination with custom headers
+$ hookdeck connection create \
+  --source-name "webhook-source" \
+  --source-type HTTP \
+  --destination-name "custom-api" \
+  --destination-type HTTP \
+  --destination-url "https://api.example.com/webhooks"
+```
+
+#### Configure retry rules
+
+Add automatic retry logic with exponential or linear backoff:
+
+```sh
+# Exponential backoff retry strategy
+$ hookdeck connection create \
+  --source-name "payment-webhooks" \
+  --source-type STRIPE \
+  --destination-name "payment-api" \
+  --destination-type HTTP \
+  --destination-url "https://api.example.com/payments" \
+  --rule-retry-strategy exponential \
+  --rule-retry-count 5 \
+  --rule-retry-interval 60000
+```
+
+#### Add event filters
+
+Filter events based on request body, headers, path, or query parameters:
+
+```sh
+# Filter by event type in body
+$ hookdeck connection create \
+  --source-name "events" \
+  --source-type HTTP \
+  --destination-name "processor" \
+  --destination-type HTTP \
+  --destination-url "https://api.example.com/process" \
+  --rule-filter-body '{"event_type":"payment.succeeded"}'
+
+# Combined filtering
+$ hookdeck connection create \
+  --source-name "shopify-webhooks" \
+  --source-type SHOPIFY \
+  --destination-name "order-processor" \
+  --destination-type HTTP \
+  --destination-url "https://api.example.com/orders" \
+  --rule-filter-body '{"type":"order"}' \
+  --rule-retry-strategy exponential \
+  --rule-retry-count 3
+```
+
+#### Configure rate limiting
+
+Control the rate of event delivery to your destination:
+
+```sh
+# Limit to 100 requests per minute
+$ hookdeck connection create \
+  --source-name "high-volume-source" \
+  --source-type HTTP \
+  --destination-name "rate-limited-api" \
+  --destination-type HTTP \
+  --destination-url "https://api.example.com/endpoint" \
+  --destination-rate-limit 100 \
+  --destination-rate-limit-period minute
+```
+
+#### Upsert connections
+
+Create or update connections idempotently based on connection name - perfect for CI/CD and infrastructure-as-code workflows:
+
+```sh
+# Create if doesn't exist, update if it does
+$ hookdeck connection upsert my-connection \
+  --source-name "stripe-prod" \
+  --source-type STRIPE \
+  --destination-name "api-prod" \
+  --destination-type HTTP \
+  --destination-url "https://api.example.com"
+
+# Partial update of existing connection
+$ hookdeck connection upsert my-connection \
+  --description "Updated description" \
+  --rule-retry-count 5
+
+# Preview changes without applying (dry-run)
+$ hookdeck connection upsert my-connection \
+  --description "New description" \
+  --dry-run
+
+-- Dry Run: UPDATE --
+Connection 'my-connection' (conn_123) will be updated with the following changes:
+- Description: "New description"
+```
+
+#### List and filter connections
+
+View all connections with flexible filtering options:
+
+```sh
+# List all connections
+$ hookdeck connection list
+
+# Filter by source or destination
+$ hookdeck connection list --source src_abc123
+$ hookdeck connection list --destination dest_xyz789
+
+# Filter by name pattern
+$ hookdeck connection list --name "production-*"
+
+# Include disabled or paused connections
+$ hookdeck connection list --disabled
+$ hookdeck connection list --paused
+
+# Output as JSON
+$ hookdeck connection list --output json
+```
+
+#### Get connection details
+
+View detailed information about a specific connection:
+
+```sh
+# Get by ID
+$ hookdeck connection get conn_123abc
+
+# Get by name
+$ hookdeck connection get "my-connection"
+
+# Get as JSON
+$ hookdeck connection get conn_123abc --output json
+```
+
+#### Connection lifecycle management
+
+Control connection state and event processing behavior:
+
+```sh
+# Disable a connection (stops receiving events entirely)
+$ hookdeck connection disable conn_123abc
+
+# Enable a disabled connection
+$ hookdeck connection enable conn_123abc
+
+# Pause a connection (queues events without forwarding)
+$ hookdeck connection pause conn_123abc
+
+# Resume a paused connection
+$ hookdeck connection unpause conn_123abc
+
+# Archive a connection (hide from main lists)
+$ hookdeck connection archive conn_123abc
+
+# Restore an archived connection
+$ hookdeck connection unarchive conn_123abc
+```
+
+**State differences:**
+- **Disabled**: Connection stops receiving events entirely
+- **Paused**: Connection queues events but doesn't forward them (useful during maintenance)
+- **Archived**: Connection is hidden from main lists but can be restored
+
+#### Delete a connection
+
+Delete a connection permanently:
+
+```sh
+# Delete with confirmation prompt
+$ hookdeck connection delete conn_123abc
+
+# Delete by name
+$ hookdeck connection delete "my-connection"
+
+# Skip confirmation
+$ hookdeck connection delete conn_123abc --force
+```
+
+For complete flag documentation and all examples, see the [CLI reference](https://hookdeck.com/docs/cli?ref=github-hookdeck-cli).
+
 ## Configuration files
 
 The Hookdeck CLI uses configuration files to store the your keys, project settings, profiles, and other configurations.
@@ -340,9 +801,9 @@ The Hookdeck CLI uses configuration files to store the your keys, project settin
 
 The CLI will look for the configuration file in the following order:
 
-  1. The `--config` flag, which allows you to specify a custom configuration file name and path per command.
-  2. The local directory `.hookdeck/config.toml`.
-  3. The default global configuration file location.
+1. The `--config` flag, which allows you to specify a custom configuration file name and path per command.
+2. The local directory `.hookdeck/config.toml`.
+3. The default global configuration file location.
 
 ### Default configuration Location
 
@@ -415,13 +876,13 @@ hookdeck listen 3030 webhooks -p prod
 
 The following flags can be used with any command:
 
-*   `--api-key`: Your API key to use for the command.
-*   `--color`: Turn on/off color output (on, off, auto).
-*   `--config`: Path to a specific configuration file.
-*   `--device-name`: A unique name for your device.
-*   `--insecure`: Allow invalid TLS certificates.
-*   `--log-level`: Set the logging level (debug, info, warn, error).
-*   `--profile` or `-p`: Use a specific configuration profile.
+- `--api-key`: Your API key to use for the command.
+- `--color`: Turn on/off color output (on, off, auto).
+- `--config`: Path to a specific configuration file.
+- `--device-name`: A unique name for your device.
+- `--insecure`: Allow invalid TLS certificates.
+- `--log-level`: Set the logging level (debug, info, warn, error).
+- `--profile` or `-p`: Use a specific configuration profile.
 
 There are also some hidden flags that are mainly used for development and debugging:
 
@@ -430,6 +891,24 @@ There are also some hidden flags that are mainly used for development and debugg
 *   `--console-base`: Sets the web console base URL.
 *   `--ws-base`: Sets the Websocket base URL.
 
+## Troubleshooting
+
+### Homebrew: Binary Already Exists Error
+
+If you previously installed Hookdeck via the Homebrew formula and are upgrading to the cask version, you may see:
+
+```
+Warning: It seems there is already a Binary at '/opt/homebrew/bin/hookdeck'
+from formula hookdeck; skipping link.
+```
+
+To resolve this, uninstall the old formula version first, then install the cask:
+
+```sh
+brew uninstall hookdeck
+brew install --cask hookdeck/hookdeck/hookdeck
+```
+
 
 ## Developing
 
@@ -451,6 +930,40 @@ Then run the locally generated `hookdeck-cli` binary:
 ./hookdeck-cli
 ```
 
+## Testing
+
+### Running Acceptance Tests
+
+The Hookdeck CLI includes comprehensive acceptance tests written in Go. These tests verify end-to-end functionality by executing the CLI and validating outputs.
+
+**Local testing:**
+
+```bash
+# Run all acceptance tests
+go test ./test/acceptance/... -v
+
+# Run specific test
+go test ./test/acceptance/... -v -run TestCLIBasics
+
+# Skip acceptance tests (short mode)
+go test ./test/acceptance/... -short
+```
+
+**Environment setup:**
+
+For local testing, create a `.env` file in `test/acceptance/`:
+
+```bash
+# test/acceptance/.env
+HOOKDECK_CLI_TESTING_API_KEY=your_api_key_here
+```
+
+**CI/CD:**
+
+In CI environments, set the `HOOKDECK_CLI_TESTING_API_KEY` environment variable directly in your workflow configuration or repository secrets.
+
+For detailed testing documentation and troubleshooting, see [`test/acceptance/README.md`](test/acceptance/README.md).
+
 ### Testing against a local API
 
 When testing against a non-production Hookdeck API, you can use the
@@ -471,6 +984,90 @@ docker run --rm -it \
     http://host.docker.internal:1234
 ```
 
+## Releasing
+
+This section describes the branching strategy and release process for the Hookdeck CLI.
+
+### Branching Strategy
+
+The project uses two primary branches:
+
+- **`main`** - The stable, production-ready branch. All production releases are created from this branch.
+- **`next`** - The beta/pre-release branch. All new features are merged here first for testing before being promoted to `main`.
+
+### Beta Releases
+
+Beta releases allow you to publish pre-release versions for testing without blocking the `main` branch or affecting stable releases.
+
+**Process:**
+
+1. Ensure all desired features are merged into the `next` branch
+2. Pull the latest changes locally:
+   ```sh
+   git checkout next
+   git pull origin next
+   ```
+3. Create and push a beta tag with a pre-release identifier:
+   ```sh
+   git tag v1.2.3-beta.0
+   git push origin v1.2.3-beta.0
+   ```
+4. The GitHub Actions workflow will automatically:
+   - Build binaries for all platforms (macOS, Linux, Windows)
+   - Create a GitHub pre-release (marked as "Pre-release")
+   - Publish to NPM with the `beta` tag
+   - Create beta packages:
+     - Homebrew: `hookdeck-beta` formula
+     - Scoop: `hookdeck-beta` package
+     - Docker: Tagged with the version (e.g., `v1.2.3-beta.0`), but not `latest`
+
+**Installing beta releases:**
+
+```sh
+# NPM
+npm install hookdeck-cli@beta -g
+
+# Homebrew
+brew install hookdeck/hookdeck/hookdeck-beta
+
+# Scoop
+scoop install hookdeck-beta
+
+# Docker
+docker run hookdeck/hookdeck-cli:v1.2.3-beta.0 version
+```
+
+### Production Releases
+
+Production releases are created from the `main` branch using GitHub's release interface.
+
+**Process:**
+
+1. Merge the `next` branch into `main`:
+   ```sh
+   git checkout main
+   git pull origin main
+   git merge next
+   git push origin main
+   ```
+2. Go to the [GitHub Releases page](https://github.com/hookdeck/hookdeck-cli/releases)
+3. Click "Draft a new release"
+4. Create a new tag with a stable version (e.g., `v1.3.0`)
+5. Target the `main` branch
+6. Generate release notes or write them manually
+7. Publish the release
+
+The GitHub Actions workflow will automatically:
+- Build binaries for all platforms
+- Create a stable GitHub release
+- Publish to NPM with the `latest` tag
+- Update package managers:
+  - Homebrew: `hookdeck` formula
+  - Scoop: `hookdeck` package
+  - Docker: Updates both the version tag and `latest`
+
+**Note:** Only stable releases (without pre-release identifiers) will update the `latest` tags across all distribution channels.
+
 ## License
 
 Copyright (c) Hookdeck. All rights reserved.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hookdeck-cli",
-  "version": "1.0.4",
+  "version": "1.2.0-beta.1",
   "description": "Hookdeck CLI",
   "repository": {
     "type": "git",