@zapier/zapier-sdk-cli 0.44.1 → 0.46.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @zapier/zapier-sdk-cli
 
+## 0.46.0
+
+### Minor Changes
+
+- 774e9d3: Add `(Enter custom value)` sentinel to dynamic-resolver dropdowns in the CLI. Selecting it opens a free-text prompt and returns the typed value, so users can supply IDs that aren't in the fetched list without rerunning the command with a CLI flag. Shown for every single-select dynamic resolver; suppressed on checkbox (multi-select) prompts where a typed scalar can't merge with the user's other selections.
+
+## 0.45.0
+
+### Minor Changes
+
+- 529663c: Add experimental support for triggers.
+
+### Patch Changes
+
+- Updated dependencies [529663c]
+  - @zapier/zapier-sdk-mcp@0.13.0
+  - @zapier/zapier-sdk@0.49.0
+
 ## 0.44.1
 
 ### Patch Changes

package/README.md

@@ -13,10 +13,10 @@
   - [`logout`](#logout)
 - [Actions](#actions)
   - [`get-action`](#get-action)
-  - [`get-input-fields-schema`](#get-input-fields-schema)
+  - [`get-action-input-fields-schema`](#get-action-input-fields-schema)
+  - [`list-action-input-field-choices`](#list-action-input-field-choices)
+  - [`list-action-input-fields`](#list-action-input-fields)
   - [`list-actions`](#list-actions)
-  - [`list-input-field-choices`](#list-input-field-choices)
-  - [`list-input-fields`](#list-input-fields)
   - [`run-action`](#run-action)
 - [Apps](#apps)
   - [`get-app`](#get-app)
@@ -45,6 +45,24 @@
   - [`list-table-records`](#list-table-records)
   - [`list-tables`](#list-tables)
   - [`update-table-records`](#update-table-records)
+- [Triggers (Experimental)](#triggers-experimental)
+  - [`ack-trigger-inbox-messages`](#ack-trigger-inbox-messages--experimental)
+  - [`create-trigger-inbox`](#create-trigger-inbox--experimental)
+  - [`delete-trigger-inbox`](#delete-trigger-inbox--experimental)
+  - [`drain-trigger-inbox`](#drain-trigger-inbox--experimental)
+  - [`ensure-trigger-inbox`](#ensure-trigger-inbox--experimental)
+  - [`get-trigger-inbox`](#get-trigger-inbox--experimental)
+  - [`get-trigger-input-fields-schema`](#get-trigger-input-fields-schema--experimental)
+  - [`lease-trigger-inbox-messages`](#lease-trigger-inbox-messages--experimental)
+  - [`list-trigger-inbox-messages`](#list-trigger-inbox-messages--experimental)
+  - [`list-trigger-inboxes`](#list-trigger-inboxes--experimental)
+  - [`list-trigger-input-field-choices`](#list-trigger-input-field-choices--experimental)
+  - [`list-trigger-input-fields`](#list-trigger-input-fields--experimental)
+  - [`pause-trigger-inbox`](#pause-trigger-inbox--experimental)
+  - [`release-trigger-inbox-messages`](#release-trigger-inbox-messages--experimental)
+  - [`resume-trigger-inbox`](#resume-trigger-inbox--experimental)
+  - [`update-trigger-inbox`](#update-trigger-inbox--experimental)
+  - [`watch-trigger-inbox`](#watch-trigger-inbox--experimental)
 - [Utilities](#utilities)
   - [`add`](#add)
   - [`build-manifest`](#build-manifest)
@@ -195,7 +213,7 @@ Get detailed information about a specific action
 npx zapier-sdk get-action <app> <action-type> <action>
 ```
 
-#### `get-input-fields-schema`
+#### `get-action-input-fields-schema`
 
 Get the JSON Schema representation of input fields for an action. Returns a JSON Schema object describing the structure, types, and validation rules for the action's input parameters.
 
@@ -212,30 +230,10 @@ Get the JSON Schema representation of input fields for an action. Returns a JSON
 **Usage:**
 
 ```bash
-npx zapier-sdk get-input-fields-schema <app> <action-type> <action> [--connection] [--inputs]
+npx zapier-sdk get-action-input-fields-schema <app> <action-type> <action> [--connection] [--inputs]
 ```
 
-#### `list-actions`
-
-List all actions for a specific app
-
-**Options:**
-
-| Option          | Type     | Required | Default | Possible Values                                                                                | Description                                                            |
-| --------------- | -------- | -------- | ------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
-| `<app>`         | `string` | ✅       | —       | —                                                                                              | App key of actions to list (e.g., 'SlackCLIAPI' or slug like 'github') |
-| `--action-type` | `string` | ❌       | —       | `read`, `read_bulk`, `write`, `run`, `search`, `search_or_write`, `search_and_write`, `filter` | Filter actions by type                                                 |
-| `--page-size`   | `number` | ❌       | —       | —                                                                                              | Number of actions per page                                             |
-| `--max-items`   | `number` | ❌       | —       | —                                                                                              | Maximum total items to return across all pages                         |
-| `--cursor`      | `string` | ❌       | —       | —                                                                                              | Cursor to start from                                                   |
-
-**Usage:**
-
-```bash
-npx zapier-sdk list-actions <app> [--action-type] [--page-size] [--max-items] [--cursor]
-```
-
-#### `list-input-field-choices`
+#### `list-action-input-field-choices`
 
 Get the available choices for a dynamic dropdown input field
 
@@ -257,10 +255,10 @@ Get the available choices for a dynamic dropdown input field
 **Usage:**
 
 ```bash
-npx zapier-sdk list-input-field-choices <app> <action-type> <action> <input-field> [--connection] [--inputs] [--page] [--page-size] [--max-items] [--cursor]
+npx zapier-sdk list-action-input-field-choices <app> <action-type> <action> <input-field> [--connection] [--inputs] [--page] [--page-size] [--max-items] [--cursor]
 ```
 
-#### `list-input-fields`
+#### `list-action-input-fields`
 
 Get the input fields required for a specific action
 
@@ -280,7 +278,27 @@ Get the input fields required for a specific action
 **Usage:**
 
 ```bash
-npx zapier-sdk list-input-fields <app> <action-type> <action> [--connection] [--inputs] [--page-size] [--max-items] [--cursor]
+npx zapier-sdk list-action-input-fields <app> <action-type> <action> [--connection] [--inputs] [--page-size] [--max-items] [--cursor]
+```
+
+#### `list-actions`
+
+List all actions for a specific app
+
+**Options:**
+
+| Option          | Type     | Required | Default | Possible Values                                                                                | Description                                                            |
+| --------------- | -------- | -------- | ------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `<app>`         | `string` | ✅       | —       | —                                                                                              | App key of actions to list (e.g., 'SlackCLIAPI' or slug like 'github') |
+| `--action-type` | `string` | ❌       | —       | `read`, `read_bulk`, `write`, `run`, `search`, `search_or_write`, `search_and_write`, `filter` | Filter actions by type                                                 |
+| `--page-size`   | `number` | ❌       | —       | —                                                                                              | Number of actions per page                                             |
+| `--max-items`   | `number` | ❌       | —       | —                                                                                              | Maximum total items to return across all pages                         |
+| `--cursor`      | `string` | ❌       | —       | —                                                                                              | Cursor to start from                                                   |
+
+**Usage:**
+
+```bash
+npx zapier-sdk list-actions <app> [--action-type] [--page-size] [--max-items] [--cursor]
 ```
 
 #### `run-action`
@@ -750,6 +768,340 @@ Update one or more records in a table
 npx zapier-sdk update-table-records <table> <records> [--key-mode]
 ```
 
+### Triggers (Experimental)
+
+> Experimental. Run via the `zapier-sdk-experimental` bin (or pass `--experimental` to `zapier-sdk`). Flags and behavior may change between versions, and availabilitiy may be limited to some users.
+
+#### `ack-trigger-inbox-messages` 🧪 _experimental_
+
+Acknowledge messages from a lease. Acked messages are removed from the inbox; unacked ones return to the available pool when the lease expires.
+
+**Options:**
+
+| Option       | Type     | Required | Default | Possible Values | Description                                                                                                |
+| ------------ | -------- | -------- | ------- | --------------- | ---------------------------------------------------------------------------------------------------------- |
+| `<inbox>`    | `string` | ✅       | —       | —               | Trigger inbox identifier — UUID or name. Non-UUID values are resolved by name via the inbox list endpoint. |
+| `<lease>`    | `string` | ✅       | —       | —               | Lease ID returned from leaseTriggerInboxMessages                                                           |
+| `--messages` | `array`  | ❌       | —       | —               | Specific message IDs to ack. Omit to ack every message in the lease.                                       |
+
+**Usage:**
+
+```bash
+npx zapier-sdk ack-trigger-inbox-messages <inbox> <lease> [--messages]
+```
+
+#### `create-trigger-inbox` 🧪 _experimental_
+
+Create a new trigger inbox subscription with an auto-generated name. Always creates; use ensureTriggerInbox for get-or-create on a stable name.
+
+**Options:**
+
+| Option               | Type             | Required | Default | Possible Values | Description                                                                                                  |
+| -------------------- | ---------------- | -------- | ------- | --------------- | ------------------------------------------------------------------------------------------------------------ |
+| `<app>`              | `string`         | ✅       | —       | —               | App slug (e.g., 'github'), implementation name (e.g., 'SlackCLIAPI'), or versioned ID (e.g., 'github@1.2.3') |
+| `<action>`           | `string`         | ✅       | —       | —               | Action key (e.g., 'send_message' or 'find_row')                                                              |
+| `--connection`       | `string, number` | ❌       | —       | —               | Connection alias or connection ID. Optional for triggers that don't require auth.                            |
+| `--inputs`           | `object`         | ❌       | —       | —               | Input parameters for the trigger subscription                                                                |
+| `--notification-url` | `string`         | ❌       | —       | —               | Webhook URL to POST to when new messages arrive                                                              |
+
+**Usage:**
+
+```bash
+npx zapier-sdk create-trigger-inbox <app> <action> [--connection] [--inputs] [--notification-url]
+```
+
+#### `delete-trigger-inbox` 🧪 _experimental_
+
+Mark a trigger inbox for deletion
+
+**Options:**
+
+| Option    | Type     | Required | Default | Possible Values | Description                                                                                                |
+| --------- | -------- | -------- | ------- | --------------- | ---------------------------------------------------------------------------------------------------------- |
+| `<inbox>` | `string` | ✅       | —       | —               | Trigger inbox identifier — UUID or name. Non-UUID values are resolved by name via the inbox list endpoint. |
+
+**Usage:**
+
+```bash
+npx zapier-sdk delete-trigger-inbox <inbox>
+```
+
+#### `drain-trigger-inbox` 🧪 _experimental_
+
+Drain an existing trigger inbox: lease currently-available messages, process each via onMessage, return when the inbox is empty, maxMessages is reached, or the abort signal fires.
+
+**Options:**
+
+| Option                | Type      | Required | Default | Possible Values | Description                                                                                                                                                                                                                                                                                       |
+| --------------------- | --------- | -------- | ------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `<inbox>`             | `string`  | ✅       | —       | —               | Trigger inbox identifier — UUID or name. Non-UUID values are resolved by name via the inbox list endpoint.                                                                                                                                                                                        |
+| `--concurrency`       | `number`  | ❌       | —       | —               | Per-message handler workers running in parallel. Defaults to `leaseLimit`, or 1 if neither is set.                                                                                                                                                                                                |
+| `--lease-limit`       | `number`  | ❌       | —       | —               | Per-lease HTTP batch size. Defaults to `concurrency`, or 1 if neither is set.                                                                                                                                                                                                                     |
+| `--lease-seconds`     | `number`  | ❌       | —       | —               | Seconds until the lease expires; messages return to available if not acked. API default is 300 (5 minutes).                                                                                                                                                                                       |
+| `--release-on-error`  | `boolean` | ❌       | —       | —               | If true, errors immediately release the message. If false (default), errors leave it leased until the lease timeout. `ZapierReleaseTriggerMessageSignal` always releases regardless.                                                                                                              |
+| `--continue-on-error` | `boolean` | ❌       | —       | —               | If false (default, fail-fast), the first handler error rejects and stops the drain. If true, handler errors are observed via `onError` and the drain continues. SDK-level errors (lease / ack / release) reject regardless.                                                                       |
+| `--max-messages`      | `number`  | ❌       | —       | —               | Cap total messages drained. Defaults to draining the inbox until empty.                                                                                                                                                                                                                           |
+| `--exec`              | `string`  | ❌       | —       | —               | Run a binary per message with no shell interpretation. Message JSON is piped to stdin; exit code 0 acks, non-zero records the error per the same rules as a thrown handler. Pass extra argv after `--` (e.g. `--exec ./handler -- --verbose`). Mutually exclusive with --exec-shell and --json.   |
+| `--exec-shell`        | `string`  | ❌       | —       | —               | Run a shell command per message. Message JSON is piped to the subprocess on stdin; exit code 0 acks, non-zero records the error per the same rules as a thrown handler. Interpreted by the platform's default shell (sh on POSIX, cmd.exe on Windows). Mutually exclusive with --exec and --json. |
+| `--json`              | `boolean` | ❌       | —       | —               | Format the drained result as a JSON object on stdout: { data, errors }. Use for scripts or piping. Mutually exclusive with --exec / --exec-shell and the interactive default.                                                                                                                     |
+
+**Usage:**
+
+```bash
+npx zapier-sdk drain-trigger-inbox <inbox> [--concurrency] [--lease-limit] [--lease-seconds] [--release-on-error] [--continue-on-error] [--max-messages] [--exec] [--exec-shell] [--json]
+```
+
+#### `ensure-trigger-inbox` 🧪 _experimental_
+
+Get-or-create a trigger inbox by name. Idempotent on (user, account, name): returns the existing inbox if a matching subscription is registered, creates a new one otherwise. Throws ZapierConflictError if the name exists with a different subscription.
+
+**Options:**
+
+| Option               | Type             | Required | Default | Possible Values | Description                                                                                                                                                             |
+| -------------------- | ---------------- | -------- | ------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `<name>`             | `string`         | ✅       | —       | —               | Inbox name; serves as the idempotency key. Required for ensureTriggerInbox — without one, the API mints a fresh inbox each call (use createTriggerInbox for that path). |
+| `<app>`              | `string`         | ✅       | —       | —               | App slug (e.g., 'github'), implementation name (e.g., 'SlackCLIAPI'), or versioned ID (e.g., 'github@1.2.3')                                                            |
+| `<action>`           | `string`         | ✅       | —       | —               | Action key (e.g., 'send_message' or 'find_row')                                                                                                                         |
+| `--connection`       | `string, number` | ❌       | —       | —               | Connection alias or connection ID. Optional for triggers that don't require auth.                                                                                       |
+| `--inputs`           | `object`         | ❌       | —       | —               | Input parameters for the trigger subscription                                                                                                                           |
+| `--notification-url` | `string`         | ❌       | —       | —               | Webhook URL to POST to when new messages arrive                                                                                                                         |
+
+**Usage:**
+
+```bash
+npx zapier-sdk ensure-trigger-inbox <name> <app> <action> [--connection] [--inputs] [--notification-url]
+```
+
+#### `get-trigger-inbox` 🧪 _experimental_
+
+Get details of a trigger inbox by ID
+
+**Options:**
+
+| Option    | Type     | Required | Default | Possible Values | Description                                                                                                |
+| --------- | -------- | -------- | ------- | --------------- | ---------------------------------------------------------------------------------------------------------- |
+| `<inbox>` | `string` | ✅       | —       | —               | Trigger inbox identifier — UUID or name. Non-UUID values are resolved by name via the inbox list endpoint. |
+
+**Usage:**
+
+```bash
+npx zapier-sdk get-trigger-inbox <inbox>
+```
+
+#### `get-trigger-input-fields-schema` 🧪 _experimental_
+
+Get the JSON Schema representation of input fields for a trigger. Returns a JSON Schema object describing the structure, types, and validation rules for the trigger's input parameters.
+
+**Options:**
+
+| Option         | Type             | Required | Default | Possible Values | Description                                                                                                  |
+| -------------- | ---------------- | -------- | ------- | --------------- | ------------------------------------------------------------------------------------------------------------ |
+| `<app>`        | `string`         | ✅       | —       | —               | App key (e.g., 'SlackCLIAPI' or slug like 'github') to get the input schema for                              |
+| `<action>`     | `string`         | ✅       | —       | —               | Trigger action key to get the input schema for                                                               |
+| `--connection` | `string, number` | ❌       | —       | —               | Connection alias or connection ID. Required if the trigger needs a connection to determine available fields. |
+| `--inputs`     | `object`         | ❌       | —       | —               | Current input values that may affect the schema (e.g., when fields depend on other field values)             |
+
+**Usage:**
+
+```bash
+npx zapier-sdk get-trigger-input-fields-schema <app> <action> [--connection] [--inputs]
+```
+
+#### `lease-trigger-inbox-messages` 🧪 _experimental_
+
+Lease up to N messages from a trigger inbox. Returns messages plus a lease ID; ack within the lease window to remove from the inbox.
+
+**Options:**
+
+| Option            | Type     | Required | Default | Possible Values | Description                                                                                                 |
+| ----------------- | -------- | -------- | ------- | --------------- | ----------------------------------------------------------------------------------------------------------- |
+| `<inbox>`         | `string` | ✅       | —       | —               | Trigger inbox identifier — UUID or name. Non-UUID values are resolved by name via the inbox list endpoint.  |
+| `--lease-limit`   | `number` | ❌       | —       | —               | Maximum messages to lease in a single batch (1-100)                                                         |
+| `--lease-seconds` | `number` | ❌       | —       | —               | Seconds until the lease expires; messages return to available if not acked. API default is 300 (5 minutes). |
+
+**Usage:**
+
+```bash
+npx zapier-sdk lease-trigger-inbox-messages <inbox> [--lease-limit] [--lease-seconds]
+```
+
+#### `list-trigger-inbox-messages` 🧪 _experimental_
+
+List messages in a trigger inbox (no payload, status-only)
+
+**Options:**
+
+| Option        | Type     | Required | Default | Possible Values | Description                                                                                                |
+| ------------- | -------- | -------- | ------- | --------------- | ---------------------------------------------------------------------------------------------------------- |
+| `<inbox>`     | `string` | ✅       | —       | —               | Trigger inbox identifier — UUID or name. Non-UUID values are resolved by name via the inbox list endpoint. |
+| `--page-size` | `number` | ❌       | —       | —               | Number of messages per page                                                                                |
+| `--max-items` | `number` | ❌       | —       | —               | Maximum total items to return across all pages                                                             |
+| `--cursor`    | `string` | ❌       | —       | —               | Pagination cursor                                                                                          |
+
+**Usage:**
+
+```bash
+npx zapier-sdk list-trigger-inbox-messages <inbox> [--page-size] [--max-items] [--cursor]
+```
+
+#### `list-trigger-inboxes` 🧪 _experimental_
+
+List all trigger inboxes for the authenticated user
+
+**Options:**
+
+| Option        | Type     | Required | Default | Possible Values                                                          | Description                                                                                                  |
+| ------------- | -------- | -------- | ------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
+| `--name`      | `string` | ❌       | —       | —                                                                        | Filter by inbox name (exact match). Names are unique per (user, account), so this returns at most one inbox. |
+| `--status`    | `string` | ❌       | —       | `initializing`, `active`, `paused`, `deleting`, `initialization_failure` | Filter by inbox status                                                                                       |
+| `--page-size` | `number` | ❌       | —       | —                                                                        | Number of inboxes per page                                                                                   |
+| `--max-items` | `number` | ❌       | —       | —                                                                        | Maximum total items to return across all pages                                                               |
+| `--cursor`    | `string` | ❌       | —       | —                                                                        | Cursor (offset) to start from for pagination                                                                 |
+
+**Usage:**
+
+```bash
+npx zapier-sdk list-trigger-inboxes [--name] [--status] [--page-size] [--max-items] [--cursor]
+```
+
+#### `list-trigger-input-field-choices` 🧪 _experimental_
+
+Get the available choices for a dynamic dropdown input field on a trigger
+
+**Options:**
+
+| Option          | Type             | Required | Default | Possible Values | Description                                                                                                         |
+| --------------- | ---------------- | -------- | ------- | --------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `<app>`         | `string`         | ✅       | —       | —               | App slug (e.g., 'github'), implementation name (e.g., 'SlackCLIAPI'), or versioned ID (e.g., 'github@1.2.3')        |
+| `<action>`      | `string`         | ✅       | —       | —               | Action key (e.g., 'send_message' or 'find_row')                                                                     |
+| `<input-field>` | `string`         | ✅       | —       | —               | Input field key to get choices for                                                                                  |
+| `--connection`  | `string, number` | ❌       | —       | —               | Connection alias or connection ID. Required if the trigger needs a connection to populate dynamic dropdown options. |
+| `--inputs`      | `object`         | ❌       | —       | —               | Current input values that may affect available choices                                                              |
+| `--page`        | `number`         | ❌       | —       | —               | Page number for paginated results                                                                                   |
+| `--page-size`   | `number`         | ❌       | —       | —               | Number of choices per page                                                                                          |
+| `--max-items`   | `number`         | ❌       | —       | —               | Maximum total items to return across all pages                                                                      |
+| `--cursor`      | `string`         | ❌       | —       | —               | Cursor to start from                                                                                                |
+
+**Usage:**
+
+```bash
+npx zapier-sdk list-trigger-input-field-choices <app> <action> <input-field> [--connection] [--inputs] [--page] [--page-size] [--max-items] [--cursor]
+```
+
+#### `list-trigger-input-fields` 🧪 _experimental_
+
+Get the input fields required for a specific trigger
+
+**Options:**
+
+| Option         | Type             | Required | Default | Possible Values | Description                                                                                                  |
+| -------------- | ---------------- | -------- | ------- | --------------- | ------------------------------------------------------------------------------------------------------------ |
+| `<app>`        | `string`         | ✅       | —       | —               | App slug (e.g., 'github'), implementation name (e.g., 'SlackCLIAPI'), or versioned ID (e.g., 'github@1.2.3') |
+| `<action>`     | `string`         | ✅       | —       | —               | Action key (e.g., 'send_message' or 'find_row')                                                              |
+| `--connection` | `string, number` | ❌       | —       | —               | Connection alias or connection ID. Required if the trigger needs a connection to determine available fields. |
+| `--inputs`     | `object`         | ❌       | —       | —               | Current input values that may affect available fields                                                        |
+| `--page-size`  | `number`         | ❌       | —       | —               | Number of input fields per page                                                                              |
+| `--max-items`  | `number`         | ❌       | —       | —               | Maximum total items to return across all pages                                                               |
+| `--cursor`     | `string`         | ❌       | —       | —               | Cursor to start from                                                                                         |
+
+**Usage:**
+
+```bash
+npx zapier-sdk list-trigger-input-fields <app> <action> [--connection] [--inputs] [--page-size] [--max-items] [--cursor]
+```
+
+#### `pause-trigger-inbox` 🧪 _experimental_
+
+Pause a trigger inbox; events stop being collected
+
+**Options:**
+
+| Option    | Type     | Required | Default | Possible Values | Description                                                                                                |
+| --------- | -------- | -------- | ------- | --------------- | ---------------------------------------------------------------------------------------------------------- |
+| `<inbox>` | `string` | ✅       | —       | —               | Trigger inbox identifier — UUID or name. Non-UUID values are resolved by name via the inbox list endpoint. |
+
+**Usage:**
+
+```bash
+npx zapier-sdk pause-trigger-inbox <inbox>
+```
+
+#### `release-trigger-inbox-messages` 🧪 _experimental_
+
+Release messages from a lease back to the inbox without acknowledging them. Released messages become immediately available for re-leasing. The lease attempt still counts against the per-message lease limit; releasing does not refund the attempt.
+
+**Options:**
+
+| Option       | Type     | Required | Default | Possible Values | Description                                                                                                |
+| ------------ | -------- | -------- | ------- | --------------- | ---------------------------------------------------------------------------------------------------------- |
+| `<inbox>`    | `string` | ✅       | —       | —               | Trigger inbox identifier — UUID or name. Non-UUID values are resolved by name via the inbox list endpoint. |
+| `<lease>`    | `string` | ✅       | —       | —               | Lease ID returned from leaseTriggerInboxMessages                                                           |
+| `--messages` | `array`  | ❌       | —       | —               | Specific message IDs to release. Omit to release every message in the lease.                               |
+
+**Usage:**
+
+```bash
+npx zapier-sdk release-trigger-inbox-messages <inbox> <lease> [--messages]
+```
+
+#### `resume-trigger-inbox` 🧪 _experimental_
+
+Resume a paused trigger inbox; events resume being collected
+
+**Options:**
+
+| Option    | Type     | Required | Default | Possible Values | Description                                                                                                |
+| --------- | -------- | -------- | ------- | --------------- | ---------------------------------------------------------------------------------------------------------- |
+| `<inbox>` | `string` | ✅       | —       | —               | Trigger inbox identifier — UUID or name. Non-UUID values are resolved by name via the inbox list endpoint. |
+
+**Usage:**
+
+```bash
+npx zapier-sdk resume-trigger-inbox <inbox>
+```
+
+#### `update-trigger-inbox` 🧪 _experimental_
+
+Update settings on an existing trigger inbox
+
+**Options:**
+
+| Option               | Type     | Required | Default | Possible Values | Description                                                                                                |
+| -------------------- | -------- | -------- | ------- | --------------- | ---------------------------------------------------------------------------------------------------------- |
+| `<inbox>`            | `string` | ✅       | —       | —               | Trigger inbox identifier — UUID or name. Non-UUID values are resolved by name via the inbox list endpoint. |
+| `--notification-url` | `string` | ❌       | —       | —               | Webhook URL to POST to when new messages arrive. Pass null to clear.                                       |
+
+**Usage:**
+
+```bash
+npx zapier-sdk update-trigger-inbox <inbox> [--notification-url]
+```
+
+#### `watch-trigger-inbox` 🧪 _experimental_
+
+Continuously consume a trigger inbox: drain currently-available messages via onMessage, then poll with backoff for new arrivals, until aborted. Resolves cleanly on signal abort or ZapierAbortDrainSignal from a handler; rejects on fatal SDK errors or fail-fast handler errors.
+
+**Options:**
+
+| Option                         | Type      | Required | Default | Possible Values | Description                                                                                                                                                                                                                                                                                       |
+| ------------------------------ | --------- | -------- | ------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `<inbox>`                      | `string`  | ✅       | —       | —               | Trigger inbox identifier — UUID or name. Non-UUID values are resolved by name via the inbox list endpoint.                                                                                                                                                                                        |
+| `--concurrency`                | `number`  | ❌       | —       | —               | Per-message handler workers running in parallel. Defaults to `leaseLimit`, or 1 if neither is set.                                                                                                                                                                                                |
+| `--lease-limit`                | `number`  | ❌       | —       | —               | Per-lease HTTP batch size. Defaults to `concurrency`, or 1 if neither is set.                                                                                                                                                                                                                     |
+| `--lease-seconds`              | `number`  | ❌       | —       | —               | Seconds until the lease expires; messages return to available if not acked. API default is 300 (5 minutes).                                                                                                                                                                                       |
+| `--release-on-error`           | `boolean` | ❌       | —       | —               | If true, errors immediately release the message. If false (default), errors leave it leased until the lease timeout. `ZapierReleaseTriggerMessageSignal` always releases regardless.                                                                                                              |
+| `--continue-on-error`          | `boolean` | ❌       | —       | —               | If false (default, fail-fast), the first handler error rejects and stops the drain. If true, handler errors are observed via `onError` and the drain continues. SDK-level errors (lease / ack / release) reject regardless.                                                                       |
+| `--max-drain-interval-seconds` | `number`  | ❌       | —       | —               | Maximum seconds between empty-inbox poll attempts (default: 60). Caps the back-off cadence.                                                                                                                                                                                                       |
+| `--exec`                       | `string`  | ❌       | —       | —               | Run a binary per message with no shell interpretation. Message JSON is piped to stdin; exit code 0 acks, non-zero records the error per the same rules as a thrown handler. Pass extra argv after `--` (e.g. `--exec ./handler -- --verbose`). Mutually exclusive with --exec-shell and --json.   |
+| `--exec-shell`                 | `string`  | ❌       | —       | —               | Run a shell command per message. Message JSON is piped to the subprocess on stdin; exit code 0 acks, non-zero records the error per the same rules as a thrown handler. Interpreted by the platform's default shell (sh on POSIX, cmd.exe on Windows). Mutually exclusive with --exec and --json. |
+| `--json`                       | `boolean` | ❌       | —       | —               | Stream each message as JSON to stdout (one record per line, NDJSON), acking as each write completes. Use for piping to other tools. Mutually exclusive with --exec / --exec-shell and the interactive default.                                                                                    |
+
+**Usage:**
+
+```bash
+npx zapier-sdk watch-trigger-inbox <inbox> [--concurrency] [--lease-limit] [--lease-seconds] [--release-on-error] [--continue-on-error] [--max-drain-interval-seconds] [--exec] [--exec-shell] [--json]
+```
+
 ### Utilities
 
 #### `add`

package/bin/zapier-sdk-experimental.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+
+// The experimental bin loads the same compiled CLI as the stable bin
+// but injects --experimental into argv first. cli.ts only has one
+// detection path (argv flag + env var), so this bin and
+// `zapier-sdk --experimental` are byte-equivalent at the CLI's view
+// of argv. Renaming this file later doesn't break detection — the
+// signal is what we push, not what we're called.
+//
+// Dynamic import (rather than the static `import "..."` form) is
+// load-bearing: a static import is hoisted above the argv mutation,
+// so cli.mjs would see the unmodified argv.
+process.argv.push("--experimental");
+await import("../dist/cli.mjs");