@zapier/zapier-sdk-cli 0.87.2 → 0.87.4

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 +18 -0
  2. package/README.md +281 -257
  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-ARSBOJ1p.d.mts} +3 -3
  10. package/dist/{extensions-CrfC6xjA.d.ts → extensions-ARSBOJ1p.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 +4 -4
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,6 +331,8 @@ 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.
@@ -499,6 +503,8 @@ npx zapier-sdk run-action <app> <action-type> <action> [--connection] [--inputs]
499
503
 
500
504
  ### Apps
501
505
 
506
+ 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.
507
+
502
508
  #### `get-app`
503
509
 
504
510
  Get detailed information about a specific app
@@ -537,6 +543,8 @@ npx zapier-sdk list-apps [--search] [--page-size] [--apps] [--max-items] [--curs
537
543
 
538
544
  ### Client Credentials
539
545
 
546
+ 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.
547
+
540
548
  #### `create-client-credentials`
541
549
 
542
550
  Create new client credentials for the authenticated user
@@ -585,10 +593,260 @@ List client credentials for the authenticated user
585
593
  **Usage:**
586
594
 
587
595
  ```bash
588
- npx zapier-sdk list-client-credentials [--page-size] [--max-items] [--cursor]
596
+ npx zapier-sdk list-client-credentials [--page-size] [--max-items] [--cursor]
597
+ ```
598
+
599
+ ### Connections
600
+
601
+ 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.
602
+
603
+ #### `create-connection`
604
+
605
+ 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.
606
+
607
+ 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`.
608
+
609
+ **Options:**
610
+
611
+ | Option | Type | Required | Default | Possible Values | Description |
612
+ | ------------------------------ | -------- | -------- | -------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
613
+ | `<app>` | `string` | ✅ | — | — | App slug (e.g., 'github'), implementation name (e.g., 'SlackCLIAPI'), or versioned ID (e.g., 'github@1.2.3') |
614
+ | `--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. |
615
+ | `--timeout-seconds` | `number` | ❌ | — | — | How long to wait for the user to complete the connection flow before giving up. Default 5 minutes (300). |
616
+ | `--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). |
617
+
618
+ **Usage:**
619
+
620
+ ```bash
621
+ npx zapier-sdk create-connection <app> [--browser] [--timeout-seconds] [--poll-interval-milliseconds]
622
+ ```
623
+
624
+ #### `find-first-connection`
625
+
626
+ Find the first connection matching the criteria
627
+
628
+ **Options:**
629
+
630
+ | Option | Type | Required | Default | Possible Values | Description |
631
+ | ------------------ | --------- | -------- | ------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
632
+ | `[app]` | `string` | ❌ | — | — | App key of connections to list (e.g., 'SlackCLIAPI' or slug like 'github') |
633
+ | `--search` | `string` | ❌ | — | — | Search term to filter connections by title |
634
+ | `--title` | `string` | ❌ | — | — | Filter connections by exact title match (searches first, then filters locally) |
635
+ | `--owner` | `string` | ❌ | — | — | Filter by owner, 'me' for your own connections or a specific user ID |
636
+ | `--account` | `string` | ❌ | — | — | Account to filter by |
637
+ | `--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. |
638
+ | `--status` | `string` | ❌ | — | `active`, `expired`, `all` | Filter connections by expiry: 'active' (default) returns only non-expired connections, 'expired' only expired ones, and 'all' returns both. |
639
+
640
+ **Usage:**
641
+
642
+ ```bash
643
+ npx zapier-sdk find-first-connection [app] [--search] [--title] [--owner] [--account] [--include-shared] [--status]
644
+ ```
645
+
646
+ #### `find-unique-connection`
647
+
648
+ Find a unique connection matching the criteria
649
+
650
+ **Options:**
651
+
652
+ | Option | Type | Required | Default | Possible Values | Description |
653
+ | ------------------ | --------- | -------- | ------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
654
+ | `[app]` | `string` | ❌ | — | — | App key of connections to list (e.g., 'SlackCLIAPI' or slug like 'github') |
655
+ | `--search` | `string` | ❌ | — | — | Search term to filter connections by title |
656
+ | `--title` | `string` | ❌ | — | — | Filter connections by exact title match (searches first, then filters locally) |
657
+ | `--owner` | `string` | ❌ | — | — | Filter by owner, 'me' for your own connections or a specific user ID |
658
+ | `--account` | `string` | ❌ | — | — | Account to filter by |
659
+ | `--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. |
660
+ | `--status` | `string` | ❌ | — | `active`, `expired`, `all` | Filter connections by expiry: 'active' (default) returns only non-expired connections, 'expired' only expired ones, and 'all' returns both. |
661
+
662
+ **Usage:**
663
+
664
+ ```bash
665
+ npx zapier-sdk find-unique-connection [app] [--search] [--title] [--owner] [--account] [--include-shared] [--status]
666
+ ```
667
+
668
+ #### `get-connection`
669
+
670
+ Get details for a specific connection
671
+
672
+ **Options:**
673
+
674
+ | Option | Type | Required | Default | Possible Values | Description |
675
+ | -------------- | ---------------- | -------- | ------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
676
+ | `<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. |
677
+
678
+ **Usage:**
679
+
680
+ ```bash
681
+ npx zapier-sdk get-connection <connection>
682
+ ```
683
+
684
+ #### `get-connection-start-url`
685
+
686
+ 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.
687
+
688
+ 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.
689
+
690
+ 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):
691
+
692
+ ```ts
693
+ const {
694
+ data: { url, app, startedAt },
695
+ } = await zapier.getConnectionStartUrl({ app: "slack" });
696
+ // hand `url` off — print it, DM it, email it, render a button, whatever
697
+ const { data: conn } = await zapier.waitForNewConnection({ app, startedAt });
698
+ ```
699
+
700
+ **Options:**
701
+
702
+ | Option | Type | Required | Default | Possible Values | Description |
703
+ | ------- | -------- | -------- | ------- | --------------- | ------------------------------------------------------------------------------------------------------------ |
704
+ | `<app>` | `string` | ✅ | — | — | App slug (e.g., 'github'), implementation name (e.g., 'SlackCLIAPI'), or versioned ID (e.g., 'github@1.2.3') |
705
+
706
+ **Usage:**
707
+
708
+ ```bash
709
+ npx zapier-sdk get-connection-start-url <app>
710
+ ```
711
+
712
+ #### `list-connections`
713
+
714
+ List available connections with optional filtering
715
+
716
+ **Options:**
717
+
718
+ | Option | Type | Required | Default | Possible Values | Description |
719
+ | ------------------ | --------- | -------- | ------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
720
+ | `[app]` | `string` | ❌ | — | — | App key of connections to list (e.g., 'SlackCLIAPI' or slug like 'github') |
721
+ | `--search` | `string` | ❌ | — | — | Search term to filter connections by title |
722
+ | `--title` | `string` | ❌ | — | — | Filter connections by exact title match (searches first, then filters locally) |
723
+ | `--owner` | `string` | ❌ | — | — | Filter by owner, 'me' for your own connections or a specific user ID |
724
+ | `--connections` | `array` | ❌ | — | — | List of connection IDs to filter by |
725
+ | `--account` | `string` | ❌ | — | — | Account to filter by |
726
+ | `--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. |
727
+ | `--status` | `string` | ❌ | — | `active`, `expired`, `all` | Filter connections by expiry: 'active' (default) returns only non-expired connections, 'expired' only expired ones, and 'all' returns both. |
728
+ | `--page-size` | `number` | ❌ | — | — | Number of connections per page. The upstream API may cap this and reject values above its limit. |
729
+ | `--max-items` | `number` | ❌ | — | — | Maximum total items to return across all pages |
730
+ | `--cursor` | `string` | ❌ | — | — | Cursor to start from |
731
+
732
+ **Usage:**
733
+
734
+ ```bash
735
+ npx zapier-sdk list-connections [app] [--search] [--title] [--owner] [--connections] [--account] [--include-shared] [--status] [--page-size] [--max-items] [--cursor]
736
+ ```
737
+
738
+ #### `wait-for-new-connection`
739
+
740
+ 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):
741
+
742
+ ```ts
743
+ const {
744
+ data: { url, app, startedAt },
745
+ } = await zapier.getConnectionStartUrl({ app: "slack" });
746
+ // show `url` to the user via the channel they're reading from
747
+ const { data: conn } = await zapier.waitForNewConnection({ app, startedAt });
748
+ ```
749
+
750
+ **Options:**
751
+
752
+ | Option | Type | Required | Default | Possible Values | Description |
753
+ | ------------------------------ | -------- | -------- | ------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
754
+ | `<app>` | `string` | ✅ | — | — | App slug (e.g., 'github'), implementation name (e.g., 'SlackCLIAPI'), or versioned ID (e.g., 'github@1.2.3') |
755
+ | `<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. |
756
+ | `--timeout-seconds` | `number` | ❌ | — | — | How long to wait before giving up. Default 5 minutes (300). |
757
+ | `--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). |
758
+
759
+ **Usage:**
760
+
761
+ ```bash
762
+ npx zapier-sdk wait-for-new-connection <app> <started-at> [--timeout-seconds] [--poll-interval-milliseconds]
763
+ ```
764
+
765
+ ### HTTP Requests
766
+
767
+ 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.
768
+
769
+ #### `curl`
770
+
771
+ 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.
772
+
773
+ **Options:**
774
+
775
+ | Option | Type | Required | Default | Possible Values | Description |
776
+ | ------------------ | ---------------- | -------- | ------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
777
+ | `<url>` | `string` | ✅ | — | — | Request URL |
778
+ | `--request` | `string` | ❌ | — | `GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `HEAD`, `OPTIONS` | HTTP method (defaults to GET, or POST if data is provided) |
779
+ | `--header` | `array` | ❌ | — | — | HTTP headers in 'Key: Value' format (repeatable) |
780
+ | `--data` | `array` | ❌ | — | — | HTTP POST data (repeatable, joined with &) |
781
+ | `--data-raw` | `array` | ❌ | — | — | HTTP POST data without special interpretation (repeatable) |
782
+ | `--data-ascii` | `array` | ❌ | — | — | HTTP POST ASCII data (repeatable) |
783
+ | `--data-binary` | `array` | ❌ | — | — | HTTP POST binary data (repeatable) |
784
+ | `--data-urlencode` | `array` | ❌ | — | — | HTTP POST data, URL-encoded (repeatable) |
785
+ | `--json` | `string` | ❌ | — | — | Send JSON body (sets Content-Type and Accept headers) |
786
+ | `--form` | `array` | ❌ | — | — | Multipart form data as 'name=value' (repeatable) |
787
+ | `--form-string` | `array` | ❌ | — | — | Multipart form string field (repeatable) |
788
+ | `--get` | `boolean` | ❌ | — | — | Force GET method and append data to query string |
789
+ | `--head` | `boolean` | ❌ | — | — | Fetch headers only (HEAD request) |
790
+ | `--location` | `boolean` | ❌ | — | — | Follow redirects |
791
+ | `--include` | `boolean` | ❌ | — | — | Include response headers in output |
792
+ | `--output` | `string` | ❌ | — | — | Write output to file instead of stdout |
793
+ | `--remote-name` | `boolean` | ❌ | — | — | Write output to file named like the remote file |
794
+ | `--verbose` | `boolean` | ❌ | — | — | Verbose output (show request/response headers on stderr) |
795
+ | `--silent` | `boolean` | ❌ | — | — | Silent mode (suppress errors) |
796
+ | `--show-error` | `boolean` | ❌ | — | — | Show errors even when in silent mode |
797
+ | `--fail` | `boolean` | ❌ | — | — | Fail silently on HTTP errors (exit code 22) |
798
+ | `--fail-with-body` | `boolean` | ❌ | — | — | Fail on HTTP errors but still output the body |
799
+ | `--write-out` | `string` | ❌ | — | — | Output format string after completion (e.g., '%{http_code}') |
800
+ | `--max-time` | `number` | ❌ | — | — | Maximum seconds to wait for a response. Honored on a best-effort basis; the server may silently enforce a lower ceiling. |
801
+ | `--user` | `string` | ❌ | — | — | Basic auth credentials as 'user:password' |
802
+ | `--compressed` | `boolean` | ❌ | — | — | Request compressed response (sends Accept-Encoding header) |
803
+ | `--connection` | `string, number` | ❌ | — | — | Zapier connection ID or alias for authentication |
804
+
805
+ **Usage:**
806
+
807
+ ```bash
808
+ 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]
809
+ ```
810
+
811
+ ### Human Inputs (Experimental)
812
+
813
+ Collect information from people with Zapier Forms. Use these to create a form and share its link to gather responses.
814
+
815
+ > ℹ️ **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.
816
+
817
+ #### `create-form` 🧪 _experimental_
818
+
819
+ 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.
820
+
821
+ **Options:**
822
+
823
+ | Option | Type | Required | Default | Possible Values | Description |
824
+ | ------------------------ | --------- | -------- | ------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
825
+ | `<title>` | `string` | ✅ | — | — | The title shown in the Forms UI and on the form. |
826
+ | `--description` | `string` | ❌ | — | — | An optional description of the form. |
827
+ | `--fields` | `array` | ❌ | — | — | Initial fields to add to the form. |
828
+ | `--draft` | `boolean` | ❌ | — | — | When true, save without publishing. Omit to publish immediately, making `hosted_url` live. |
829
+ | `--confirmation-title` | `string` | ❌ | — | — | Heading shown to the respondent after they submit. Omit to use the form renderer's default. |
830
+ | `--confirmation-message` | `string` | ❌ | — | — | Message shown to the respondent after they submit, below the confirmation title. Omit to use the form renderer's default. |
831
+ | `--callback-url` | `string` | ❌ | — | — | Absolute http/https URL notified with the submission JSON each time the form is answered. |
832
+ | `--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. |
833
+ | `--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. |
834
+ | ​ ↳ `id` | `string` | ✅ | — | — | |
835
+ | ​ ↳ `type` | `string` | ✅ | — | `root` | |
836
+ | ​ ↳ `attrs` | `object` | ✅ | — | — | |
837
+ | ​   ↳ `schema_version` | `number` | ✅ | — | — | |
838
+ | ​   ↳ `title` | `string` | ✅ | — | — | |
839
+ | ​ ↳ `children` | `array` | ❌ | — | — | |
840
+
841
+ **Usage:**
842
+
843
+ ```bash
844
+ npx zapier-sdk create-form <title> [--description] [--fields] [--draft] [--confirmation-title] [--confirmation-message] [--callback-url] [--consumer-auth] [--document]
589
845
  ```
590
846
 
591
- ### Code Workflows (Experimental)
847
+ ### Next Gen Zaps (Experimental)
848
+
849
+ 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
850
 
593
851
  > ℹ️ **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
852
 
@@ -1192,250 +1450,10 @@ Validate durable workflow source without publishing it. Returns source diagnosti
1192
1450
  npx zapier-sdk validate-workflow <source-files> [--entrypoint-file]
1193
1451
  ```
1194
1452
 
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
1453
  ### Tables
1438
1454
 
1455
+ Tables is Zapier's database tool for storing and managing data. Use these to manage tables, their fields, and their records.
1456
+
1439
1457
  #### `create-table`
1440
1458
 
1441
1459
  Create a new table
@@ -1658,6 +1676,8 @@ npx zapier-sdk update-table-records <table> <records> [--key-mode]
1658
1676
 
1659
1677
  ### Triggers
1660
1678
 
1679
+ 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.
1680
+
1661
1681
  #### `ack-trigger-inbox-messages`
1662
1682
 
1663
1683
  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 +2030,8 @@ npx zapier-sdk watch-trigger-inbox <inbox> [--concurrency] [--lease-limit] [--le
2010
2030
 
2011
2031
  ### Utilities
2012
2032
 
2033
+ Commands for setting up and working with the SDK in a project, like creating a project, adding apps, and generating TypeScript types.
2034
+
2013
2035
  #### `add`
2014
2036
 
2015
2037
  Add apps with manifest locking and TypeScript type generation - updates .zapierrc with app versions and generates TypeScript definition files
@@ -2148,6 +2170,8 @@ npx zapier-sdk setup [--agent] [--step] [--non-interactive] [--answer] [--flow]
2148
2170
 
2149
2171
  ### Virtual File System (Experimental)
2150
2172
 
2173
+ The Virtual File System is file storage hosted by Zapier. Use these to read, write, and organize files and folders.
2174
+
2151
2175
  > ℹ️ **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
2176
 
2153
2177
  #### `append-vfs-file` 🧪 _experimental_