@zapier/zapier-sdk-cli 0.87.3 → 0.88.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (15) hide show
  1. package/CHANGELOG.md +22 -0
  2. package/README.md +305 -279
  3. package/dist/cli.cjs +17 -17
  4. package/dist/cli.mjs +18 -18
  5. package/dist/experimental.cjs +17 -17
  6. package/dist/experimental.d.mts +1 -1
  7. package/dist/experimental.d.ts +1 -1
  8. package/dist/experimental.mjs +18 -18
  9. package/dist/{extensions-CrfC6xjA.d.mts → extensions-3Zg4od8c.d.mts} +3 -3
  10. package/dist/{extensions-CrfC6xjA.d.ts → extensions-3Zg4od8c.d.ts} +3 -3
  11. package/dist/index.cjs +17 -17
  12. package/dist/index.d.mts +1 -1
  13. package/dist/index.d.ts +1 -1
  14. package/dist/index.mjs +18 -18
  15. package/package.json +5 -5
package/README.md CHANGED
@@ -29,7 +29,19 @@
29
29
  - [`create-client-credentials`](#create-client-credentials)
30
30
  - [`delete-client-credentials`](#delete-client-credentials)
31
31
  - [`list-client-credentials`](#list-client-credentials)
32
- - [Code Workflows (Experimental)](#code-workflows-experimental)
32
+ - [Connections](#connections)
33
+ - [`create-connection`](#create-connection)
34
+ - [`find-first-connection`](#find-first-connection)
35
+ - [`find-unique-connection`](#find-unique-connection)
36
+ - [`get-connection`](#get-connection)
37
+ - [`get-connection-start-url`](#get-connection-start-url)
38
+ - [`list-connections`](#list-connections)
39
+ - [`wait-for-new-connection`](#wait-for-new-connection)
40
+ - [HTTP Requests](#http-requests)
41
+ - [`curl`](#curl)
42
+ - [Human Inputs (Experimental)](#human-inputs-experimental)
43
+ - [`create-form`](#create-form--experimental)
44
+ - [Next Gen Zaps (Experimental)](#next-gen-zaps-experimental)
33
45
  - [`cancel-durable-run`](#cancel-durable-run--experimental)
34
46
  - [`create-workflow`](#create-workflow--experimental)
35
47
  - [`create-workflow-draft`](#create-workflow-draft--experimental)
@@ -63,18 +75,6 @@
63
75
  - [`update-workflow`](#update-workflow--experimental)
64
76
  - [`update-workflow-draft`](#update-workflow-draft--experimental)
65
77
  - [`validate-workflow`](#validate-workflow--experimental)
66
- - [Connections](#connections)
67
- - [`create-connection`](#create-connection)
68
- - [`find-first-connection`](#find-first-connection)
69
- - [`find-unique-connection`](#find-unique-connection)
70
- - [`get-connection`](#get-connection)
71
- - [`get-connection-start-url`](#get-connection-start-url)
72
- - [`list-connections`](#list-connections)
73
- - [`wait-for-new-connection`](#wait-for-new-connection)
74
- - [HTTP Requests](#http-requests)
75
- - [`curl`](#curl)
76
- - [Human Inputs (Experimental)](#human-inputs-experimental)
77
- - [`create-form`](#create-form--experimental)
78
78
  - [Tables](#tables)
79
79
  - [`create-table`](#create-table)
80
80
  - [`create-table-fields`](#create-table-fields)
@@ -266,6 +266,8 @@ Boolean flags are presence toggles and take no value: pass `--flag` to enable it
266
266
 
267
267
  ### Accounts
268
268
 
269
+ Your Zapier user account, the one the SDK is signed in as. Use these to check who that is.
270
+
269
271
  #### `get-profile`
270
272
 
271
273
  Get current user's profile information
@@ -329,26 +331,29 @@ npx zapier-sdk signup [--timeout] [--use-approvals] [--non-interactive] [--headl
329
331
 
330
332
  ### Actions
331
333
 
334
+ An action is something an app can do, like sending an email or creating a contact. Use these to find an app's actions, see what inputs they need, and run them directly, outside a Zap.
335
+
332
336
  #### `create-action-run`
333
337
 
334
338
  Start an action run and return its ID without waiting for the result. Running an action is asynchronous: this hands back a run ID immediately, and `getActionRun` fetches the outcome. Reach for this pair when you want to start work and collect it later (fan out many runs, hand the ID to another process, survive a restart). `runAction` is the one-call form that starts a run and waits for its result.
335
339
 
336
340
  **Options:**
337
341
 
338
- | Option | Type | Required | Default | Possible Values | Description |
339
- | ---------------- | ---------------- | -------- | ------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
340
- | `<app>` | `string` | ✅ | — | — | App slug (e.g., 'github'), implementation name (e.g., 'SlackCLIAPI'), or versioned ID (e.g., 'github@1.2.3') |
341
- | `<action-type>` | `string` | ✅ | — | `read`, `read_bulk`, `write`, `run`, `search`, `search_or_write`, `search_and_write`, `filter` | Action type that matches the action's defined type |
342
- | `<action>` | `string` | ✅ | — | — | Action key (e.g., 'send_message' or 'find_row') |
343
- | `--connection` | `string, number` | ❌ | — | — | Connection alias or connection ID (UUID or positive integer). Required if the action needs a connection to authenticate and interact with the service. Strings that match a key in the connections map are resolved against it; otherwise the value is used as a connection ID directly. |
344
- | `--inputs` | `object` | ❌ | — | — | Input parameters for the action |
345
- | `--page` | `string` | ❌ | — | — | Page to fetch for bulk read actions. Pass the `next_page` a previous run returned to fetch the following page. |
346
- | `--callback-url` | `string` | ❌ | — | — | URL Zapier posts the finished run to, so you do not have to poll for it. Must use HTTPS and resolve to a public host, so a local receiver needs a tunnel. The body matches what `getActionRun` returns. Verify the `Zapier-Callback-Signature` header, and expect the same run to arrive more than once. |
342
+ | Option | Type | Required | Default | Possible Values | Description |
343
+ | ------------------- | ---------------- | -------- | ------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
344
+ | `<app>` | `string` | ✅ | — | — | App slug (e.g., 'github'), implementation name (e.g., 'SlackCLIAPI'), or versioned ID (e.g., 'github@1.2.3') |
345
+ | `<action-type>` | `string` | ✅ | — | `read`, `read_bulk`, `write`, `run`, `search`, `search_or_write`, `search_and_write`, `filter` | Action type that matches the action's defined type |
346
+ | `<action>` | `string` | ✅ | — | — | Action key (e.g., 'send_message' or 'find_row') |
347
+ | `--connection` | `string, number` | ❌ | — | — | Connection alias or connection ID (UUID or positive integer). Required if the action needs a connection to authenticate and interact with the service. Strings that match a key in the connections map are resolved against it; otherwise the value is used as a connection ID directly. |
348
+ | `--inputs` | `object` | ❌ | — | — | Input parameters for the action |
349
+ | `--page` | `string` | ❌ | — | — | Page to fetch for bulk read actions. Pass the `next_page` a previous run returned to fetch the following page. |
350
+ | `--callback-url` | `string` | ❌ | — | — | URL Zapier posts the finished run to, so you do not have to poll for it. Must use HTTPS and resolve to a public host, so a local receiver needs a tunnel. The body matches what `getActionRun` returns. Verify the `Zapier-Callback-Signature` header, and expect the same run to arrive more than once. |
351
+ | `--idempotency-key` | `string` | ❌ | — | — | Key that makes retrying a run safe. Another run with the same key within 72 hours returns the original run instead of starting a new one, even if its inputs differ, so use a fresh key per distinct run. A paged run is sent with a key derived from this key and the page, so one key covers every page and retrying a page replays that page's run. |
347
352
 
348
353
  **Usage:**
349
354
 
350
355
  ```bash
351
- npx zapier-sdk create-action-run <app> <action-type> <action> [--connection] [--inputs] [--page] [--callback-url]
356
+ npx zapier-sdk create-action-run <app> <action-type> <action> [--connection] [--inputs] [--page] [--callback-url] [--idempotency-key]
352
357
  ```
353
358
 
354
359
  #### `get-action`
@@ -479,26 +484,29 @@ Execute an action with the given inputs and wait for its results. Each result pa
479
484
 
480
485
  **Options:**
481
486
 
482
- | Option | Type | Required | Default | Possible Values | Description |
483
- | ------------------- | ---------------- | -------- | ------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
484
- | `<app>` | `string` | ✅ | — | — | App slug (e.g., 'github'), implementation name (e.g., 'SlackCLIAPI'), or versioned ID (e.g., 'github@1.2.3') |
485
- | `<action-type>` | `string` | ✅ | — | `read`, `read_bulk`, `write`, `run`, `search`, `search_or_write`, `search_and_write`, `filter` | Action type that matches the action's defined type |
486
- | `<action>` | `string` | ✅ | — | — | Action key (e.g., 'send_message' or 'find_row') |
487
- | `--connection` | `string, number` | ❌ | — | — | Connection alias or connection ID (UUID or positive integer). Strings that match a key in the connections map are resolved against it; otherwise the value is used as a connection ID directly. Mutually exclusive with connectionId. |
488
- | `--inputs` | `object` | ❌ | — | — | Input parameters for the action |
489
- | `--timeout-seconds` | `number` | ❌ | — | — | Maximum time to wait for action completion in seconds (default: 180) |
490
- | `--page-size` | `number` | ❌ | — | — | Number of results per page |
491
- | `--max-items` | `number` | ❌ | — | — | Maximum total items to return across all pages |
492
- | `--cursor` | `string` | ❌ | — | — | Cursor to start from |
487
+ | Option | Type | Required | Default | Possible Values | Description |
488
+ | ------------------- | ---------------- | -------- | ------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
489
+ | `<app>` | `string` | ✅ | — | — | App slug (e.g., 'github'), implementation name (e.g., 'SlackCLIAPI'), or versioned ID (e.g., 'github@1.2.3') |
490
+ | `<action-type>` | `string` | ✅ | — | `read`, `read_bulk`, `write`, `run`, `search`, `search_or_write`, `search_and_write`, `filter` | Action type that matches the action's defined type |
491
+ | `<action>` | `string` | ✅ | — | — | Action key (e.g., 'send_message' or 'find_row') |
492
+ | `--connection` | `string, number` | ❌ | — | — | Connection alias or connection ID (UUID or positive integer). Strings that match a key in the connections map are resolved against it; otherwise the value is used as a connection ID directly. Mutually exclusive with connectionId. |
493
+ | `--inputs` | `object` | ❌ | — | — | Input parameters for the action |
494
+ | `--timeout-seconds` | `number` | ❌ | — | — | Maximum time to wait for action completion in seconds (default: 180) |
495
+ | `--idempotency-key` | `string` | ❌ | — | — | Key that makes retrying a run safe. Another run with the same key within 72 hours returns the original run instead of starting a new one, even if its inputs differ, so use a fresh key per distinct run. A paged run is sent with a key derived from this key and the page, so one key covers every page and retrying a page replays that page's run. |
496
+ | `--page-size` | `number` | ❌ | — | — | Number of results per page |
497
+ | `--max-items` | `number` | ❌ | — | — | Maximum total items to return across all pages |
498
+ | `--cursor` | `string` | ❌ | — | — | Cursor to start from |
493
499
 
494
500
  **Usage:**
495
501
 
496
502
  ```bash
497
- npx zapier-sdk run-action <app> <action-type> <action> [--connection] [--inputs] [--timeout-seconds] [--page-size] [--max-items] [--cursor]
503
+ npx zapier-sdk run-action <app> <action-type> <action> [--connection] [--inputs] [--timeout-seconds] [--idempotency-key] [--page-size] [--max-items] [--cursor]
498
504
  ```
499
505
 
500
506
  ### Apps
501
507
 
508
+ An app is a web service that connects with Zapier, like Gmail or Slack. Use these to find apps and the keys other methods use to refer to them.
509
+
502
510
  #### `get-app`
503
511
 
504
512
  Get detailed information about a specific app
@@ -537,6 +545,8 @@ npx zapier-sdk list-apps [--search] [--page-size] [--apps] [--max-items] [--curs
537
545
 
538
546
  ### Client Credentials
539
547
 
548
+ SDK client credentials are a client ID and client secret that authenticate your code to the Zapier SDK, separate from the connections that authenticate apps. Use these to create, list, and revoke them.
549
+
540
550
  #### `create-client-credentials`
541
551
 
542
552
  Create new client credentials for the authenticated user
@@ -585,10 +595,260 @@ List client credentials for the authenticated user
585
595
  **Usage:**
586
596
 
587
597
  ```bash
588
- npx zapier-sdk list-client-credentials [--page-size] [--max-items] [--cursor]
598
+ npx zapier-sdk list-client-credentials [--page-size] [--max-items] [--cursor]
599
+ ```
600
+
601
+ ### Connections
602
+
603
+ A connection is an authenticated link between Zapier and your account in an app, like your company's Slack workspace, made with OAuth or an API key. Use these to find existing connections or create new ones for actions, triggers, and API requests to use.
604
+
605
+ #### `create-connection`
606
+
607
+ Create a new app connection, end-to-end. Mints the start URL via `get-connection-start-url`, prints it to stderr, opportunistically opens it in a browser when it looks safe to do so (skipping CI / SSH / headless-Linux by default — pass `--browser always` to force, `--browser never` to suppress), then polls via `wait-for-new-connection` until the user completes OAuth and the new connection appears. Returns the connection.
608
+
609
+ This is the right command for most callers. Reach for the lower-level building blocks when you want either of: (a) hand off the URL and _not_ block on completion — call `get-connection-start-url` alone, no `wait-for-new-connection` needed, or (b) do something custom between minting the URL and waiting — call `get-connection-start-url`, do your work (email or DM the URL, render a QR code, etc.), then `wait-for-new-connection`.
610
+
611
+ **Options:**
612
+
613
+ | Option | Type | Required | Default | Possible Values | Description |
614
+ | ------------------------------ | -------- | -------- | -------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
615
+ | `<app>` | `string` | ✅ | — | — | App slug (e.g., 'github'), implementation name (e.g., 'SlackCLIAPI'), or versioned ID (e.g., 'github@1.2.3') |
616
+ | `--browser` | `string` | ❌ | `"auto"` | `auto`, `always`, `never` | When to auto-open the URL in a browser. `auto` (default) opens in local sessions and skips opening in CI / SSH / headless-Linux. `always` forces the open attempt. `never` skips it. The URL is always printed to stderr regardless — a failed or skipped open degrades gracefully to copy-paste. |
617
+ | `--timeout-seconds` | `number` | ❌ | — | — | How long to wait for the user to complete the connection flow before giving up. Default 5 minutes (300). |
618
+ | `--poll-interval-milliseconds` | `number` | ❌ | — | — | Delay before the first poll request, in ms. Default 3 seconds (3_000). Subsequent polling cadence is managed by the SDK's polling primitive (backoff with sane defaults). |
619
+
620
+ **Usage:**
621
+
622
+ ```bash
623
+ npx zapier-sdk create-connection <app> [--browser] [--timeout-seconds] [--poll-interval-milliseconds]
624
+ ```
625
+
626
+ #### `find-first-connection`
627
+
628
+ Find the first connection matching the criteria
629
+
630
+ **Options:**
631
+
632
+ | Option | Type | Required | Default | Possible Values | Description |
633
+ | ------------------ | --------- | -------- | ------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
634
+ | `[app]` | `string` | ❌ | — | — | App key of connections to list (e.g., 'SlackCLIAPI' or slug like 'github') |
635
+ | `--search` | `string` | ❌ | — | — | Search term to filter connections by title |
636
+ | `--title` | `string` | ❌ | — | — | Filter connections by exact title match (searches first, then filters locally) |
637
+ | `--owner` | `string` | ❌ | — | — | Filter by owner, 'me' for your own connections or a specific user ID |
638
+ | `--account` | `string` | ❌ | — | — | Account to filter by |
639
+ | `--include-shared` | `boolean` | ❌ | — | — | Include connections shared with you. By default, only your own connections are returned (owner=me). Set to true to also include shared connections. |
640
+ | `--status` | `string` | ❌ | — | `active`, `expired`, `all` | Filter connections by expiry: 'active' (default) returns only non-expired connections, 'expired' only expired ones, and 'all' returns both. |
641
+
642
+ **Usage:**
643
+
644
+ ```bash
645
+ npx zapier-sdk find-first-connection [app] [--search] [--title] [--owner] [--account] [--include-shared] [--status]
646
+ ```
647
+
648
+ #### `find-unique-connection`
649
+
650
+ Find a unique connection matching the criteria
651
+
652
+ **Options:**
653
+
654
+ | Option | Type | Required | Default | Possible Values | Description |
655
+ | ------------------ | --------- | -------- | ------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
656
+ | `[app]` | `string` | ❌ | — | — | App key of connections to list (e.g., 'SlackCLIAPI' or slug like 'github') |
657
+ | `--search` | `string` | ❌ | — | — | Search term to filter connections by title |
658
+ | `--title` | `string` | ❌ | — | — | Filter connections by exact title match (searches first, then filters locally) |
659
+ | `--owner` | `string` | ❌ | — | — | Filter by owner, 'me' for your own connections or a specific user ID |
660
+ | `--account` | `string` | ❌ | — | — | Account to filter by |
661
+ | `--include-shared` | `boolean` | ❌ | — | — | Include connections shared with you. By default, only your own connections are returned (owner=me). Set to true to also include shared connections. |
662
+ | `--status` | `string` | ❌ | — | `active`, `expired`, `all` | Filter connections by expiry: 'active' (default) returns only non-expired connections, 'expired' only expired ones, and 'all' returns both. |
663
+
664
+ **Usage:**
665
+
666
+ ```bash
667
+ npx zapier-sdk find-unique-connection [app] [--search] [--title] [--owner] [--account] [--include-shared] [--status]
668
+ ```
669
+
670
+ #### `get-connection`
671
+
672
+ Get details for a specific connection
673
+
674
+ **Options:**
675
+
676
+ | Option | Type | Required | Default | Possible Values | Description |
677
+ | -------------- | ---------------- | -------- | ------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
678
+ | `<connection>` | `string, number` | ✅ | — | — | Connection alias or connection ID (UUID or positive integer). Strings that match a key in the connections map are resolved against it; otherwise the value is used as a connection ID directly. |
679
+
680
+ **Usage:**
681
+
682
+ ```bash
683
+ npx zapier-sdk get-connection <connection>
684
+ ```
685
+
686
+ #### `get-connection-start-url`
687
+
688
+ Mint a short-lived URL that begins an SDK-initiated connection flow. The URL is signed by zapier.com and bound to the current user/account — opening it in a different browser session will fail the binding check. Returns the URL as data so the caller decides what to do with it.
689
+
690
+ Use this directly (rather than the higher-level `create-connection`) when you want either of: (a) hand off the URL and _not_ block waiting for completion — call this alone, skip `wait-for-new-connection` entirely, or (b) do something custom between minting the URL and waiting for the connection — call this, then email or DM the URL, render it as a QR code for mobile sign-in, etc., then call `wait-for-new-connection`. For the common case where you'd just print and poll back-to-back, `create-connection` is one call.
691
+
692
+ Pair with `wait-for-new-connection` to detect completion: pass the `startedAt` returned here straight through (it's the server's mint time, so polling isn't affected by client clock skew). Example (JS):
693
+
694
+ ```ts
695
+ const {
696
+ data: { url, app, startedAt },
697
+ } = await zapier.getConnectionStartUrl({ app: "slack" });
698
+ // hand `url` off — print it, DM it, email it, render a button, whatever
699
+ const { data: conn } = await zapier.waitForNewConnection({ app, startedAt });
700
+ ```
701
+
702
+ **Options:**
703
+
704
+ | Option | Type | Required | Default | Possible Values | Description |
705
+ | ------- | -------- | -------- | ------- | --------------- | ------------------------------------------------------------------------------------------------------------ |
706
+ | `<app>` | `string` | ✅ | — | — | App slug (e.g., 'github'), implementation name (e.g., 'SlackCLIAPI'), or versioned ID (e.g., 'github@1.2.3') |
707
+
708
+ **Usage:**
709
+
710
+ ```bash
711
+ npx zapier-sdk get-connection-start-url <app>
712
+ ```
713
+
714
+ #### `list-connections`
715
+
716
+ List available connections with optional filtering
717
+
718
+ **Options:**
719
+
720
+ | Option | Type | Required | Default | Possible Values | Description |
721
+ | ------------------ | --------- | -------- | ------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
722
+ | `[app]` | `string` | ❌ | — | — | App key of connections to list (e.g., 'SlackCLIAPI' or slug like 'github') |
723
+ | `--search` | `string` | ❌ | — | — | Search term to filter connections by title |
724
+ | `--title` | `string` | ❌ | — | — | Filter connections by exact title match (searches first, then filters locally) |
725
+ | `--owner` | `string` | ❌ | — | — | Filter by owner, 'me' for your own connections or a specific user ID |
726
+ | `--connections` | `array` | ❌ | — | — | List of connection IDs to filter by |
727
+ | `--account` | `string` | ❌ | — | — | Account to filter by |
728
+ | `--include-shared` | `boolean` | ❌ | — | — | Include connections shared with you. By default, only your own connections are returned (owner=me). Set to true to also include shared connections. |
729
+ | `--status` | `string` | ❌ | — | `active`, `expired`, `all` | Filter connections by expiry: 'active' (default) returns only non-expired connections, 'expired' only expired ones, and 'all' returns both. |
730
+ | `--page-size` | `number` | ❌ | — | — | Number of connections per page. The upstream API may cap this and reject values above its limit. |
731
+ | `--max-items` | `number` | ❌ | — | — | Maximum total items to return across all pages |
732
+ | `--cursor` | `string` | ❌ | — | — | Cursor to start from |
733
+
734
+ **Usage:**
735
+
736
+ ```bash
737
+ npx zapier-sdk list-connections [app] [--search] [--title] [--owner] [--connections] [--account] [--include-shared] [--status] [--page-size] [--max-items] [--cursor]
738
+ ```
739
+
740
+ #### `wait-for-new-connection`
741
+
742
+ Wait for a new connection to appear for the given app. Polls the connections list newest-first until the most recent matching row's `date` is at or after the started-at timestamp, then returns it. Pair with `get-connection-start-url` — that mints the URL the user opens, this waits for the resulting connection to land. Errors with a timeout after the configured timeout (default 5 min). Example (JS):
743
+
744
+ ```ts
745
+ const {
746
+ data: { url, app, startedAt },
747
+ } = await zapier.getConnectionStartUrl({ app: "slack" });
748
+ // show `url` to the user via the channel they're reading from
749
+ const { data: conn } = await zapier.waitForNewConnection({ app, startedAt });
750
+ ```
751
+
752
+ **Options:**
753
+
754
+ | Option | Type | Required | Default | Possible Values | Description |
755
+ | ------------------------------ | -------- | -------- | ------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
756
+ | `<app>` | `string` | ✅ | — | — | App slug (e.g., 'github'), implementation name (e.g., 'SlackCLIAPI'), or versioned ID (e.g., 'github@1.2.3') |
757
+ | `<started-at>` | `number` | ✅ | — | — | Unix timestamp (seconds). Only connections whose `date` is at or after this value count as 'new'. Prefer the `startedAt` returned by `get-connection-start-url` — it's server-stamped, so the comparison isn't thrown off by client clock skew. If you mint the timestamp yourself, capture it _before_ showing the start URL so a fast OAuth completion isn't missed. |
758
+ | `--timeout-seconds` | `number` | ❌ | — | — | How long to wait before giving up. Default 5 minutes (300). |
759
+ | `--poll-interval-milliseconds` | `number` | ❌ | — | — | Delay before the first poll request, in ms. Default 3 seconds (3_000). Subsequent polling cadence is managed by the SDK's polling primitive (backoff with sane defaults). |
760
+
761
+ **Usage:**
762
+
763
+ ```bash
764
+ npx zapier-sdk wait-for-new-connection <app> <started-at> [--timeout-seconds] [--poll-interval-milliseconds]
765
+ ```
766
+
767
+ ### HTTP Requests
768
+
769
+ Make authenticated requests to an app's API through Zapier's API proxy, using a connection's credentials so your code never handles tokens or keys. Useful when an app's actions don't cover what you need.
770
+
771
+ #### `curl`
772
+
773
+ Make authenticated HTTP requests to any API through Zapier. Pass a connection ID to automatically inject the user's stored credentials (OAuth tokens, API keys, etc.) into the outgoing request. Use it in place of the native curl command with additional Zapier-specific options.
774
+
775
+ **Options:**
776
+
777
+ | Option | Type | Required | Default | Possible Values | Description |
778
+ | ------------------ | ---------------- | -------- | ------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
779
+ | `<url>` | `string` | ✅ | — | — | Request URL |
780
+ | `--request` | `string` | ❌ | — | `GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `HEAD`, `OPTIONS` | HTTP method (defaults to GET, or POST if data is provided) |
781
+ | `--header` | `array` | ❌ | — | — | HTTP headers in 'Key: Value' format (repeatable) |
782
+ | `--data` | `array` | ❌ | — | — | HTTP POST data (repeatable, joined with &) |
783
+ | `--data-raw` | `array` | ❌ | — | — | HTTP POST data without special interpretation (repeatable) |
784
+ | `--data-ascii` | `array` | ❌ | — | — | HTTP POST ASCII data (repeatable) |
785
+ | `--data-binary` | `array` | ❌ | — | — | HTTP POST binary data (repeatable) |
786
+ | `--data-urlencode` | `array` | ❌ | — | — | HTTP POST data, URL-encoded (repeatable) |
787
+ | `--json` | `string` | ❌ | — | — | Send JSON body (sets Content-Type and Accept headers) |
788
+ | `--form` | `array` | ❌ | — | — | Multipart form data as 'name=value' (repeatable) |
789
+ | `--form-string` | `array` | ❌ | — | — | Multipart form string field (repeatable) |
790
+ | `--get` | `boolean` | ❌ | — | — | Force GET method and append data to query string |
791
+ | `--head` | `boolean` | ❌ | — | — | Fetch headers only (HEAD request) |
792
+ | `--location` | `boolean` | ❌ | — | — | Follow redirects |
793
+ | `--include` | `boolean` | ❌ | — | — | Include response headers in output |
794
+ | `--output` | `string` | ❌ | — | — | Write output to file instead of stdout |
795
+ | `--remote-name` | `boolean` | ❌ | — | — | Write output to file named like the remote file |
796
+ | `--verbose` | `boolean` | ❌ | — | — | Verbose output (show request/response headers on stderr) |
797
+ | `--silent` | `boolean` | ❌ | — | — | Silent mode (suppress errors) |
798
+ | `--show-error` | `boolean` | ❌ | — | — | Show errors even when in silent mode |
799
+ | `--fail` | `boolean` | ❌ | — | — | Fail silently on HTTP errors (exit code 22) |
800
+ | `--fail-with-body` | `boolean` | ❌ | — | — | Fail on HTTP errors but still output the body |
801
+ | `--write-out` | `string` | ❌ | — | — | Output format string after completion (e.g., '%{http_code}') |
802
+ | `--max-time` | `number` | ❌ | — | — | Maximum seconds to wait for a response. Honored on a best-effort basis; the server may silently enforce a lower ceiling. |
803
+ | `--user` | `string` | ❌ | — | — | Basic auth credentials as 'user:password' |
804
+ | `--compressed` | `boolean` | ❌ | — | — | Request compressed response (sends Accept-Encoding header) |
805
+ | `--connection` | `string, number` | ❌ | — | — | Zapier connection ID or alias for authentication |
806
+
807
+ **Usage:**
808
+
809
+ ```bash
810
+ npx zapier-sdk curl <url> [--request] [--header] [--data] [--data-raw] [--data-ascii] [--data-binary] [--data-urlencode] [--json] [--form] [--form-string] [--get] [--head] [--location] [--include] [--output] [--remote-name] [--verbose] [--silent] [--show-error] [--fail] [--fail-with-body] [--write-out] [--max-time] [--user] [--compressed] [--connection]
811
+ ```
812
+
813
+ ### Human Inputs (Experimental)
814
+
815
+ Collect information from people with Zapier Forms. Use these to create a form and share its link to gather responses.
816
+
817
+ > ℹ️ **Experimental.** Still being designed; may change shape or disappear in any release, without notice. Pass `--stability experimental` to `zapier-sdk`, or set `ZAPIER_STABILITY=experimental` in the environment, to use these commands.
818
+
819
+ #### `create-form` 🧪 _experimental_
820
+
821
+ Create a Zapier Form from a title and optional fields. Forms publish by default and return a shareable `hosted_url`; set `draft` to save without publishing.
822
+
823
+ **Options:**
824
+
825
+ | Option | Type | Required | Default | Possible Values | Description |
826
+ | ------------------------ | --------- | -------- | ------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
827
+ | `<title>` | `string` | ✅ | — | — | The title shown in the Forms UI and on the form. |
828
+ | `--description` | `string` | ❌ | — | — | An optional description of the form. |
829
+ | `--fields` | `array` | ❌ | — | — | Initial fields to add to the form. |
830
+ | `--draft` | `boolean` | ❌ | — | — | When true, save without publishing. Omit to publish immediately, making `hosted_url` live. |
831
+ | `--confirmation-title` | `string` | ❌ | — | — | Heading shown to the respondent after they submit. Omit to use the form renderer's default. |
832
+ | `--confirmation-message` | `string` | ❌ | — | — | Message shown to the respondent after they submit, below the confirmation title. Omit to use the form renderer's default. |
833
+ | `--callback-url` | `string` | ❌ | — | — | Absolute http/https URL notified with the submission JSON each time the form is answered. |
834
+ | `--consumer-auth` | `string` | ❌ | — | `none`, `zapier` | Who may open the published form. `none` (the default) leaves it public to anyone with the link; `zapier` requires the visitor to be signed in to Zapier on the form's owning account. |
835
+ | `--document` | `object` | ❌ | — | — | Escape hatch: a complete form document tree, sent as-is. When supplied it replaces the document built from `fields`, and `title`, `description`, `confirmationTitle`, and `confirmationMessage` are ignored. Use only for structures the flat field list cannot express, such as approval decisions or multi-column row layout. |
836
+ | ​ ↳ `id` | `string` | ✅ | — | — | |
837
+ | ​ ↳ `type` | `string` | ✅ | — | `root` | |
838
+ | ​ ↳ `attrs` | `object` | ✅ | — | — | |
839
+ | ​   ↳ `schema_version` | `number` | ✅ | — | — | |
840
+ | ​   ↳ `title` | `string` | ✅ | — | — | |
841
+ | ​ ↳ `children` | `array` | ❌ | — | — | |
842
+
843
+ **Usage:**
844
+
845
+ ```bash
846
+ npx zapier-sdk create-form <title> [--description] [--fields] [--draft] [--confirmation-title] [--confirmation-message] [--callback-url] [--consumer-auth] [--document]
589
847
  ```
590
848
 
591
- ### Code Workflows (Experimental)
849
+ ### Next Gen Zaps (Experimental)
850
+
851
+ Next Gen Zaps are a new version of Zaps that run on code, which makes them easier for agents and AI tools to understand. Use these to build, test, publish, and run Next Gen Zaps, and to check on their runs.
592
852
 
593
853
  > ℹ️ **Experimental.** Still being designed; may change shape or disappear in any release, without notice. Pass `--stability experimental` to `zapier-sdk`, or set `ZAPIER_STABILITY=experimental` in the environment, to use these commands.
594
854
 
@@ -1192,250 +1452,10 @@ Validate durable workflow source without publishing it. Returns source diagnosti
1192
1452
  npx zapier-sdk validate-workflow <source-files> [--entrypoint-file]
1193
1453
  ```
1194
1454
 
1195
- ### Connections
1196
-
1197
- #### `create-connection`
1198
-
1199
- Create a new app connection, end-to-end. Mints the start URL via `get-connection-start-url`, prints it to stderr, opportunistically opens it in a browser when it looks safe to do so (skipping CI / SSH / headless-Linux by default — pass `--browser always` to force, `--browser never` to suppress), then polls via `wait-for-new-connection` until the user completes OAuth and the new connection appears. Returns the connection.
1200
-
1201
- This is the right command for most callers. Reach for the lower-level building blocks when you want either of: (a) hand off the URL and _not_ block on completion — call `get-connection-start-url` alone, no `wait-for-new-connection` needed, or (b) do something custom between minting the URL and waiting — call `get-connection-start-url`, do your work (email or DM the URL, render a QR code, etc.), then `wait-for-new-connection`.
1202
-
1203
- **Options:**
1204
-
1205
- | Option | Type | Required | Default | Possible Values | Description |
1206
- | ------------------------------ | -------- | -------- | -------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1207
- | `<app>` | `string` | ✅ | — | — | App slug (e.g., 'github'), implementation name (e.g., 'SlackCLIAPI'), or versioned ID (e.g., 'github@1.2.3') |
1208
- | `--browser` | `string` | ❌ | `"auto"` | `auto`, `always`, `never` | When to auto-open the URL in a browser. `auto` (default) opens in local sessions and skips opening in CI / SSH / headless-Linux. `always` forces the open attempt. `never` skips it. The URL is always printed to stderr regardless — a failed or skipped open degrades gracefully to copy-paste. |
1209
- | `--timeout-seconds` | `number` | ❌ | — | — | How long to wait for the user to complete the connection flow before giving up. Default 5 minutes (300). |
1210
- | `--poll-interval-milliseconds` | `number` | ❌ | — | — | Delay before the first poll request, in ms. Default 3 seconds (3_000). Subsequent polling cadence is managed by the SDK's polling primitive (backoff with sane defaults). |
1211
-
1212
- **Usage:**
1213
-
1214
- ```bash
1215
- npx zapier-sdk create-connection <app> [--browser] [--timeout-seconds] [--poll-interval-milliseconds]
1216
- ```
1217
-
1218
- #### `find-first-connection`
1219
-
1220
- Find the first connection matching the criteria
1221
-
1222
- **Options:**
1223
-
1224
- | Option | Type | Required | Default | Possible Values | Description |
1225
- | ------------------ | --------- | -------- | ------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
1226
- | `[app]` | `string` | ❌ | — | — | App key of connections to list (e.g., 'SlackCLIAPI' or slug like 'github') |
1227
- | `--search` | `string` | ❌ | — | — | Search term to filter connections by title |
1228
- | `--title` | `string` | ❌ | — | — | Filter connections by exact title match (searches first, then filters locally) |
1229
- | `--owner` | `string` | ❌ | — | — | Filter by owner, 'me' for your own connections or a specific user ID |
1230
- | `--account` | `string` | ❌ | — | — | Account to filter by |
1231
- | `--include-shared` | `boolean` | ❌ | — | — | Include connections shared with you. By default, only your own connections are returned (owner=me). Set to true to also include shared connections. |
1232
- | `--status` | `string` | ❌ | — | `active`, `expired`, `all` | Filter connections by expiry: 'active' (default) returns only non-expired connections, 'expired' only expired ones, and 'all' returns both. |
1233
-
1234
- **Usage:**
1235
-
1236
- ```bash
1237
- npx zapier-sdk find-first-connection [app] [--search] [--title] [--owner] [--account] [--include-shared] [--status]
1238
- ```
1239
-
1240
- #### `find-unique-connection`
1241
-
1242
- Find a unique connection matching the criteria
1243
-
1244
- **Options:**
1245
-
1246
- | Option | Type | Required | Default | Possible Values | Description |
1247
- | ------------------ | --------- | -------- | ------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
1248
- | `[app]` | `string` | ❌ | — | — | App key of connections to list (e.g., 'SlackCLIAPI' or slug like 'github') |
1249
- | `--search` | `string` | ❌ | — | — | Search term to filter connections by title |
1250
- | `--title` | `string` | ❌ | — | — | Filter connections by exact title match (searches first, then filters locally) |
1251
- | `--owner` | `string` | ❌ | — | — | Filter by owner, 'me' for your own connections or a specific user ID |
1252
- | `--account` | `string` | ❌ | — | — | Account to filter by |
1253
- | `--include-shared` | `boolean` | ❌ | — | — | Include connections shared with you. By default, only your own connections are returned (owner=me). Set to true to also include shared connections. |
1254
- | `--status` | `string` | ❌ | — | `active`, `expired`, `all` | Filter connections by expiry: 'active' (default) returns only non-expired connections, 'expired' only expired ones, and 'all' returns both. |
1255
-
1256
- **Usage:**
1257
-
1258
- ```bash
1259
- npx zapier-sdk find-unique-connection [app] [--search] [--title] [--owner] [--account] [--include-shared] [--status]
1260
- ```
1261
-
1262
- #### `get-connection`
1263
-
1264
- Get details for a specific connection
1265
-
1266
- **Options:**
1267
-
1268
- | Option | Type | Required | Default | Possible Values | Description |
1269
- | -------------- | ---------------- | -------- | ------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1270
- | `<connection>` | `string, number` | ✅ | — | — | Connection alias or connection ID (UUID or positive integer). Strings that match a key in the connections map are resolved against it; otherwise the value is used as a connection ID directly. |
1271
-
1272
- **Usage:**
1273
-
1274
- ```bash
1275
- npx zapier-sdk get-connection <connection>
1276
- ```
1277
-
1278
- #### `get-connection-start-url`
1279
-
1280
- Mint a short-lived URL that begins an SDK-initiated connection flow. The URL is signed by zapier.com and bound to the current user/account — opening it in a different browser session will fail the binding check. Returns the URL as data so the caller decides what to do with it.
1281
-
1282
- Use this directly (rather than the higher-level `create-connection`) when you want either of: (a) hand off the URL and _not_ block waiting for completion — call this alone, skip `wait-for-new-connection` entirely, or (b) do something custom between minting the URL and waiting for the connection — call this, then email or DM the URL, render it as a QR code for mobile sign-in, etc., then call `wait-for-new-connection`. For the common case where you'd just print and poll back-to-back, `create-connection` is one call.
1283
-
1284
- Pair with `wait-for-new-connection` to detect completion: pass the `startedAt` returned here straight through (it's the server's mint time, so polling isn't affected by client clock skew). Example (JS):
1285
-
1286
- ```ts
1287
- const {
1288
- data: { url, app, startedAt },
1289
- } = await zapier.getConnectionStartUrl({ app: "slack" });
1290
- // hand `url` off — print it, DM it, email it, render a button, whatever
1291
- const { data: conn } = await zapier.waitForNewConnection({ app, startedAt });
1292
- ```
1293
-
1294
- **Options:**
1295
-
1296
- | Option | Type | Required | Default | Possible Values | Description |
1297
- | ------- | -------- | -------- | ------- | --------------- | ------------------------------------------------------------------------------------------------------------ |
1298
- | `<app>` | `string` | ✅ | — | — | App slug (e.g., 'github'), implementation name (e.g., 'SlackCLIAPI'), or versioned ID (e.g., 'github@1.2.3') |
1299
-
1300
- **Usage:**
1301
-
1302
- ```bash
1303
- npx zapier-sdk get-connection-start-url <app>
1304
- ```
1305
-
1306
- #### `list-connections`
1307
-
1308
- List available connections with optional filtering
1309
-
1310
- **Options:**
1311
-
1312
- | Option | Type | Required | Default | Possible Values | Description |
1313
- | ------------------ | --------- | -------- | ------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
1314
- | `[app]` | `string` | ❌ | — | — | App key of connections to list (e.g., 'SlackCLIAPI' or slug like 'github') |
1315
- | `--search` | `string` | ❌ | — | — | Search term to filter connections by title |
1316
- | `--title` | `string` | ❌ | — | — | Filter connections by exact title match (searches first, then filters locally) |
1317
- | `--owner` | `string` | ❌ | — | — | Filter by owner, 'me' for your own connections or a specific user ID |
1318
- | `--connections` | `array` | ❌ | — | — | List of connection IDs to filter by |
1319
- | `--account` | `string` | ❌ | — | — | Account to filter by |
1320
- | `--include-shared` | `boolean` | ❌ | — | — | Include connections shared with you. By default, only your own connections are returned (owner=me). Set to true to also include shared connections. |
1321
- | `--status` | `string` | ❌ | — | `active`, `expired`, `all` | Filter connections by expiry: 'active' (default) returns only non-expired connections, 'expired' only expired ones, and 'all' returns both. |
1322
- | `--page-size` | `number` | ❌ | — | — | Number of connections per page. The upstream API may cap this and reject values above its limit. |
1323
- | `--max-items` | `number` | ❌ | — | — | Maximum total items to return across all pages |
1324
- | `--cursor` | `string` | ❌ | — | — | Cursor to start from |
1325
-
1326
- **Usage:**
1327
-
1328
- ```bash
1329
- npx zapier-sdk list-connections [app] [--search] [--title] [--owner] [--connections] [--account] [--include-shared] [--status] [--page-size] [--max-items] [--cursor]
1330
- ```
1331
-
1332
- #### `wait-for-new-connection`
1333
-
1334
- Wait for a new connection to appear for the given app. Polls the connections list newest-first until the most recent matching row's `date` is at or after the started-at timestamp, then returns it. Pair with `get-connection-start-url` — that mints the URL the user opens, this waits for the resulting connection to land. Errors with a timeout after the configured timeout (default 5 min). Example (JS):
1335
-
1336
- ```ts
1337
- const {
1338
- data: { url, app, startedAt },
1339
- } = await zapier.getConnectionStartUrl({ app: "slack" });
1340
- // show `url` to the user via the channel they're reading from
1341
- const { data: conn } = await zapier.waitForNewConnection({ app, startedAt });
1342
- ```
1343
-
1344
- **Options:**
1345
-
1346
- | Option | Type | Required | Default | Possible Values | Description |
1347
- | ------------------------------ | -------- | -------- | ------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1348
- | `<app>` | `string` | ✅ | — | — | App slug (e.g., 'github'), implementation name (e.g., 'SlackCLIAPI'), or versioned ID (e.g., 'github@1.2.3') |
1349
- | `<started-at>` | `number` | ✅ | — | — | Unix timestamp (seconds). Only connections whose `date` is at or after this value count as 'new'. Prefer the `startedAt` returned by `get-connection-start-url` — it's server-stamped, so the comparison isn't thrown off by client clock skew. If you mint the timestamp yourself, capture it _before_ showing the start URL so a fast OAuth completion isn't missed. |
1350
- | `--timeout-seconds` | `number` | ❌ | — | — | How long to wait before giving up. Default 5 minutes (300). |
1351
- | `--poll-interval-milliseconds` | `number` | ❌ | — | — | Delay before the first poll request, in ms. Default 3 seconds (3_000). Subsequent polling cadence is managed by the SDK's polling primitive (backoff with sane defaults). |
1352
-
1353
- **Usage:**
1354
-
1355
- ```bash
1356
- npx zapier-sdk wait-for-new-connection <app> <started-at> [--timeout-seconds] [--poll-interval-milliseconds]
1357
- ```
1358
-
1359
- ### HTTP Requests
1360
-
1361
- #### `curl`
1362
-
1363
- Make authenticated HTTP requests to any API through Zapier. Pass a connection ID to automatically inject the user's stored credentials (OAuth tokens, API keys, etc.) into the outgoing request. Use it in place of the native curl command with additional Zapier-specific options.
1364
-
1365
- **Options:**
1366
-
1367
- | Option | Type | Required | Default | Possible Values | Description |
1368
- | ------------------ | ---------------- | -------- | ------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
1369
- | `<url>` | `string` | ✅ | — | — | Request URL |
1370
- | `--request` | `string` | ❌ | — | `GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `HEAD`, `OPTIONS` | HTTP method (defaults to GET, or POST if data is provided) |
1371
- | `--header` | `array` | ❌ | — | — | HTTP headers in 'Key: Value' format (repeatable) |
1372
- | `--data` | `array` | ❌ | — | — | HTTP POST data (repeatable, joined with &) |
1373
- | `--data-raw` | `array` | ❌ | — | — | HTTP POST data without special interpretation (repeatable) |
1374
- | `--data-ascii` | `array` | ❌ | — | — | HTTP POST ASCII data (repeatable) |
1375
- | `--data-binary` | `array` | ❌ | — | — | HTTP POST binary data (repeatable) |
1376
- | `--data-urlencode` | `array` | ❌ | — | — | HTTP POST data, URL-encoded (repeatable) |
1377
- | `--json` | `string` | ❌ | — | — | Send JSON body (sets Content-Type and Accept headers) |
1378
- | `--form` | `array` | ❌ | — | — | Multipart form data as 'name=value' (repeatable) |
1379
- | `--form-string` | `array` | ❌ | — | — | Multipart form string field (repeatable) |
1380
- | `--get` | `boolean` | ❌ | — | — | Force GET method and append data to query string |
1381
- | `--head` | `boolean` | ❌ | — | — | Fetch headers only (HEAD request) |
1382
- | `--location` | `boolean` | ❌ | — | — | Follow redirects |
1383
- | `--include` | `boolean` | ❌ | — | — | Include response headers in output |
1384
- | `--output` | `string` | ❌ | — | — | Write output to file instead of stdout |
1385
- | `--remote-name` | `boolean` | ❌ | — | — | Write output to file named like the remote file |
1386
- | `--verbose` | `boolean` | ❌ | — | — | Verbose output (show request/response headers on stderr) |
1387
- | `--silent` | `boolean` | ❌ | — | — | Silent mode (suppress errors) |
1388
- | `--show-error` | `boolean` | ❌ | — | — | Show errors even when in silent mode |
1389
- | `--fail` | `boolean` | ❌ | — | — | Fail silently on HTTP errors (exit code 22) |
1390
- | `--fail-with-body` | `boolean` | ❌ | — | — | Fail on HTTP errors but still output the body |
1391
- | `--write-out` | `string` | ❌ | — | — | Output format string after completion (e.g., '%{http_code}') |
1392
- | `--max-time` | `number` | ❌ | — | — | Maximum seconds to wait for a response. Honored on a best-effort basis; the server may silently enforce a lower ceiling. |
1393
- | `--user` | `string` | ❌ | — | — | Basic auth credentials as 'user:password' |
1394
- | `--compressed` | `boolean` | ❌ | — | — | Request compressed response (sends Accept-Encoding header) |
1395
- | `--connection` | `string, number` | ❌ | — | — | Zapier connection ID or alias for authentication |
1396
-
1397
- **Usage:**
1398
-
1399
- ```bash
1400
- npx zapier-sdk curl <url> [--request] [--header] [--data] [--data-raw] [--data-ascii] [--data-binary] [--data-urlencode] [--json] [--form] [--form-string] [--get] [--head] [--location] [--include] [--output] [--remote-name] [--verbose] [--silent] [--show-error] [--fail] [--fail-with-body] [--write-out] [--max-time] [--user] [--compressed] [--connection]
1401
- ```
1402
-
1403
- ### Human Inputs (Experimental)
1404
-
1405
- > ℹ️ **Experimental.** Still being designed; may change shape or disappear in any release, without notice. Pass `--stability experimental` to `zapier-sdk`, or set `ZAPIER_STABILITY=experimental` in the environment, to use these commands.
1406
-
1407
- #### `create-form` 🧪 _experimental_
1408
-
1409
- Create a Zapier Form from a title and optional fields. Forms publish by default and return a shareable `hosted_url`; set `draft` to save without publishing.
1410
-
1411
- **Options:**
1412
-
1413
- | Option | Type | Required | Default | Possible Values | Description |
1414
- | ------------------------ | --------- | -------- | ------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1415
- | `<title>` | `string` | ✅ | — | — | The title shown in the Forms UI and on the form. |
1416
- | `--description` | `string` | ❌ | — | — | An optional description of the form. |
1417
- | `--fields` | `array` | ❌ | — | — | Initial fields to add to the form. |
1418
- | `--draft` | `boolean` | ❌ | — | — | When true, save without publishing. Omit to publish immediately, making `hosted_url` live. |
1419
- | `--confirmation-title` | `string` | ❌ | — | — | Heading shown to the respondent after they submit. Omit to use the form renderer's default. |
1420
- | `--confirmation-message` | `string` | ❌ | — | — | Message shown to the respondent after they submit, below the confirmation title. Omit to use the form renderer's default. |
1421
- | `--callback-url` | `string` | ❌ | — | — | Absolute http/https URL notified with the submission JSON each time the form is answered. |
1422
- | `--consumer-auth` | `string` | ❌ | — | `none`, `zapier` | Who may open the published form. `none` (the default) leaves it public to anyone with the link; `zapier` requires the visitor to be signed in to Zapier on the form's owning account. |
1423
- | `--document` | `object` | ❌ | — | — | Escape hatch: a complete form document tree, sent as-is. When supplied it replaces the document built from `fields`, and `title`, `description`, `confirmationTitle`, and `confirmationMessage` are ignored. Use only for structures the flat field list cannot express, such as approval decisions or multi-column row layout. |
1424
- | ​ ↳ `id` | `string` | ✅ | — | — | |
1425
- | ​ ↳ `type` | `string` | ✅ | — | `root` | |
1426
- | ​ ↳ `attrs` | `object` | ✅ | — | — | |
1427
- | ​   ↳ `schema_version` | `number` | ✅ | — | — | |
1428
- | ​   ↳ `title` | `string` | ✅ | — | — | |
1429
- | ​ ↳ `children` | `array` | ❌ | — | — | |
1430
-
1431
- **Usage:**
1432
-
1433
- ```bash
1434
- npx zapier-sdk create-form <title> [--description] [--fields] [--draft] [--confirmation-title] [--confirmation-message] [--callback-url] [--consumer-auth] [--document]
1435
- ```
1436
-
1437
1455
  ### Tables
1438
1456
 
1457
+ Tables is Zapier's database tool for storing and managing data. Use these to manage tables, their fields, and their records.
1458
+
1439
1459
  #### `create-table`
1440
1460
 
1441
1461
  Create a new table
@@ -1658,6 +1678,8 @@ npx zapier-sdk update-table-records <table> <records> [--key-mode]
1658
1678
 
1659
1679
  ### Triggers
1660
1680
 
1681
+ A trigger is an event in an app that starts your automation, like a new email received. Use these to find an app's triggers and receive their events directly in your code, outside a Zap.
1682
+
1661
1683
  #### `ack-trigger-inbox-messages`
1662
1684
 
1663
1685
  Acknowledge messages from a lease. Acked messages are removed from the inbox; unacked ones return to the available pool when the lease expires.
@@ -2010,6 +2032,8 @@ npx zapier-sdk watch-trigger-inbox <inbox> [--concurrency] [--lease-limit] [--le
2010
2032
 
2011
2033
  ### Utilities
2012
2034
 
2035
+ Commands for setting up and working with the SDK in a project, like creating a project, adding apps, and generating TypeScript types.
2036
+
2013
2037
  #### `add`
2014
2038
 
2015
2039
  Add apps with manifest locking and TypeScript type generation - updates .zapierrc with app versions and generates TypeScript definition files
@@ -2148,6 +2172,8 @@ npx zapier-sdk setup [--agent] [--step] [--non-interactive] [--answer] [--flow]
2148
2172
 
2149
2173
  ### Virtual File System (Experimental)
2150
2174
 
2175
+ The Virtual File System is file storage hosted by Zapier. Use these to read, write, and organize files and folders.
2176
+
2151
2177
  > ℹ️ **Experimental.** Still being designed; may change shape or disappear in any release, without notice. Pass `--stability experimental` to `zapier-sdk`, or set `ZAPIER_STABILITY=experimental` in the environment, to use these commands.
2152
2178
 
2153
2179
  #### `append-vfs-file` 🧪 _experimental_