让开源，少一点语言距离。
npm包中文文档

@zapier/zapier-sdk-cli

中文文档
0.89.3发布于 2026/11/03SEE LICENSE IN LICENSETypeScriptESM + CJS

Command line interface for Zapier SDK

原始使用文档
中文原文
文档目录11 节
  1. Table of Contents
  2. Stability
  3. Quick Start
  4. Installation
  5. Walkthrough
  6. Global Options
  7. Available Commands
  8. Accounts
  9. Actions
  10. Apps
  11. Client Credentials

@zapier/zapier-sdk-cli

Table of Contents

Stability

Every command belongs to one of three stability tiers. Stable commands are available by default; opt into wider tiers with --stability beta / --stability experimental, or ZAPIER_STABILITY=<level> in the environment.

TierContract
StableThe surface we intend to keep. While the SDK is in Open Beta (0.x), a breaking change can still land in a minor release; we deprecate first where we can, and every one is called out in the changelog with a migration note.
BetaFunctionally complete and ready to build against, but the shape may still change as it settles. Changes land in minor releases with a changelog migration note, without a deprecation period.
ExperimentalStill being designed; may change shape or disappear in any release, without notice.

Non-stable commands are labeled in --help and print a ⚠️ BETA COMMAND / ⚠️ EXPERIMENTAL COMMAND notice when they run.

Quick Start

For new projects.

Bootstrap a new project with everything you need to start integrating thousands of apps through Zapier:

# Create a new Zapier SDK project (scaffolds files, installs deps, and logs you in).
npx @zapier/zapier-sdk-cli init my-zapier-app

# Or skip the interactive prompts and accept all defaults.
npx @zapier/zapier-sdk-cli init my-zapier-app --non-interactive

Installation

For existing projects.

Run the guided setup to add undeclared Zapier SDK dependencies, authenticate, and inspect your connected apps:

npx @zapier/zapier-sdk-cli setup

For an AI agent or another non-interactive caller, start stepwise setup:

npx @zapier/zapier-sdk-cli setup --agent

Ask the printed wizard question verbatim. After approval, run the exact setup --step <name> --non-interactive command. Use --answer for selections or text input. On success, follow the next step's guidance printed by the command; no extra --agent call is needed. The agent owns approval and progress; setup saves neither. On completion, the current agent receives instructions to suggest ideas from connected apps instead of being asked which agent to open.

Stay in the stated directory. Export shared SDK settings so later commands and generated scripts inherit them. Global CLI flags apply only to their invocation. Setup uses normal SDK credential and pending OAuth storage; a pending OAuth flow started by setup records that saved accounts must be kept. Local authorization finishes in the browser. Headless authorization asks the user to paste the final callback URL; pass it only to the printed command and do not save it. Never repeat a command whose outcome is unknown, especially a Slack send.

Printed commands pin the CLI version and use POSIX shell syntax. Agent mode uses plain text, not --json, and never reads terminal input. Ordinary setup requires a terminal and points other callers to --agent.

If you already have a project and want to add the CLI as a dependency:

npm install -D @zapier/zapier-sdk-cli

Walkthrough

# See all available commands
npx zapier-sdk --help

# Login to Zapier.
npx zapier-sdk login

# Search from thousands of supported apps.
npx zapier-sdk list-apps --search "gmail"
# The output will show you the valid keys next to the app title like this:
# 1. Gmail (GoogleMailV2CLIAPI, gmail)

# Run any action for the app, using one of the app keys.
npx zapier-sdk run-action gmail
# This will ask you for the type of action you want to run.
# `search` or `write` are typically great for testing.
# Note that you usually need a connection to the app to run
# the action. If you don't already have one, you can create a new one at:
# https://zapier.com/app/assets/connections

# List connections for an app.
npx zapier-sdk list-connections gmail
# Or only list the ones you own.
npx zapier-sdk list-connections gmail --owner me
# Or just grab the first one.
npx zapier-sdk find-first-connection gmail --owner me

# Make any API request to an app using your connection.
npx zapier-sdk curl "https://gmail.googleapis.com/gmail/v1/users/me/labels" --connection 123

Global Options

These options are available for all commands:

OptionShortDescription
--version-VDisplay version number
--help-hDisplay help for command
--stability <level>Which stability tier of the SDK / CLI surface to use: stable, beta, experimental. Can also be set with the ZAPIER_STABILITY environment variable (default: stable).
--credentials <token>Authentication token.
--credentials-client-id <id>OAuth client ID for authentication.
--credentials-client-secret <secret>OAuth client secret for authentication.
--credentials-base-url <url>Override authentication base URL.
--debugEnable debug logging.
--base-url <url>Base URL for Zapier API endpoints.
--tracking-base-url <url>Base URL for Zapier tracking endpoints.
--max-network-retries <count>Max retries for rate-limited and server-error responses (default: 3).
--max-network-retry-delay-seconds <seconds>Max delay in seconds to wait between network retries (default: 60).
--max-concurrent-requests <count>Max concurrent in-flight HTTP requests (default: 200, max: 10000).
--approval-timeout-seconds <seconds>Timeout in seconds for approval polling. Default: 600 (10 min).
--max-approval-retriesMaximum number of sequential approval rounds per request (one per gating policy) before giving up. Default: 2.
--approval-modeApproval flow behavior for manual approvals. "poll" creates the approval, opens it in a browser, polls until resolved, and retries the original request. "throw" creates the manual approval and throws a ZapierApprovalError with the approval URL so the caller can surface it. Server-created auto-mode approvals always poll until they reach a terminal status and retry the original request on approval, even when this option is "throw". "disabled" throws a ZapierApprovalError on approval-required responses without creating an approval. Resolution order is: explicit option, then ZAPIER_APPROVAL_MODE, then the default behavior (poll for interactive TTY, throw otherwise).
--open-auto-mode-approvals-in-browserBy default, auto-mode approvals do not open in a browser. Enable this option to open the approval URL and watch the approval process. Resolution order is: explicit option, then ZAPIER_OPEN_AUTO_MODE_APPROVALS_IN_BROWSER, then false.
--correlation-id <id>Correlation ID for request tracing. When set, emitted as the zapier-correlation-id header on every outbound request. Falls back to the ZAPIER_CORRELATION_ID environment variable.
--causation-id <id>Causation ID for request tracing. When set, emitted as the zapier-causation-id header on every outbound request. Falls back to the ZAPIER_CAUSATION_ID environment variable.
--can-include-shared-connectionsAllow listing shared connections.
--can-include-shared-tablesAllow listing shared tables.
--can-delete-tablesAllow deleting tables.
--jsonOutput raw JSON instead of formatted results

Available Commands

The CLI automatically generates commands from the SDK registry. All SDK functions are available as CLI commands using kebab-case naming.

Boolean flags are presence toggles and take no value: pass --flag to enable it, or omit the flag to use the default. Flags where disabling differs from omitting document a separate disable flag (e.g. --disabled). A value after a boolean flag (--flag false) is rejected as an extra argument.

Accounts

Your Zapier user account, the one the SDK is signed in as. Use these to check who that is.

get-profile

Get current user's profile information

Usage:

npx zapier-sdk get-profile

login

Log in to Zapier to access your account

Options:

OptionTypeRequiredDefaultPossible ValuesDescription
--namestring❌——Activate stored credentials with this name. If none exist, create new credentials with this name; interactive login asks for confirmation first.
--timeoutstring❌——Login timeout in seconds (default: 300)
--use-approvalsboolean❌——Require approvals for actions performed with these credentials
--non-interactiveboolean❌——Skip interactive prompts. Uses defaults where possible; errors instead of prompting when input is required. Useful in CI, piped output, or environments where TTY detection is unreliable.
--headlessboolean❌——Use when logging in from a machine that has no browser. Prints a login link to open elsewhere, then accepts the pasted loopback callback URL.
--callback-urlstring❌——Resume a pending non-interactive login with the final OAuth callback URL from your browser.

Usage:

npx zapier-sdk login [--name] [--timeout] [--use-approvals] [--non-interactive] [--headless] [--callback-url]

logout

Log out of your Zapier account

Usage:

npx zapier-sdk logout

signup

Set up Zapier account access and SDK credentials

Options:

OptionTypeRequiredDefaultPossible ValuesDescription
--timeoutstring❌——Signup timeout in seconds (default: 300)
--use-approvalsboolean❌——Require approvals for actions performed with these credentials
--non-interactiveboolean❌——Skip interactive prompts. Uses defaults where possible; errors instead of prompting when input is required. Useful in CI, piped output, or environments where TTY detection is unreliable.
--headlessboolean❌——Use when signing up from a machine that has no browser. Prints a signup link to open elsewhere, then accepts the pasted loopback callback URL.
--callback-urlstring❌——Resume a pending non-interactive signup with the final OAuth callback URL from your browser.

Usage:

npx zapier-sdk signup [--timeout] [--use-approvals] [--non-interactive] [--headless] [--callback-url]

Actions

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.

create-action-run

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.

Options:

OptionTypeRequiredDefaultPossible ValuesDescription
<app>string✅——App slug (e.g., 'github'), implementation name (e.g., 'SlackCLIAPI'), or versioned ID (e.g., '[email protected]')
<action-type>string✅—read, read_bulk, write, run, search, search_or_write, search_and_write, filterAction type that matches the action's defined type
<action>string✅——Action key (e.g., 'send_message' or 'find_row')
--connectionstring, 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.
--inputsobject❌——Input parameters for the action
--pagestring❌——Page to fetch for bulk read actions. Pass the next_page a previous run returned to fetch the following page.
--callback-urlstring❌——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.
--idempotency-keystring❌——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.

Usage:

npx zapier-sdk create-action-run <app> <action-type> <action> [--connection] [--inputs] [--page] [--callback-url] [--idempotency-key]

get-action

Get detailed information about a specific action

Options:

OptionTypeRequiredDefaultPossible ValuesDescription
<app>string✅——App slug (e.g., 'github'), implementation name (e.g., 'SlackCLIAPI'), or versioned ID (e.g., '[email protected]')
<action-type>string✅—read, read_bulk, write, run, search, search_or_write, search_and_write, filterAction type that matches the action's defined type
<action>string✅——Action key (e.g., 'send_message' or 'find_row')

Usage:

npx zapier-sdk get-action <app> <action-type> <action>

get-action-input-fields-schema

Get the JSON Schema representation of input fields for an action. Returns a JSON Schema object describing the structure, types, and validation rules for the action's input parameters.

Options:

OptionTypeRequiredDefaultPossible ValuesDescription
<app>string✅——App key (e.g., 'SlackCLIAPI' or slug like 'github') to get the input schema for
<action-type>string✅—read, read_bulk, write, run, search, search_or_write, search_and_write, filterAction type that matches the action's defined type
<action>string✅——Action key to get the input schema for
--connectionstring, 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.
--inputsobject❌——Current input values that may affect the schema (e.g., when fields depend on other field values)

Usage:

npx zapier-sdk get-action-input-fields-schema <app> <action-type> <action> [--connection] [--inputs]

get-action-run

Fetch the current state of an action run started by createActionRun. This is a point-in-time read that returns immediately: a run Zapier has not finished executing comes back with status waiting, so call again to check for a result. runAction starts a run and waits for its result in one call. Results are stored for seven days after the run was created.

Options:

OptionTypeRequiredDefaultPossible ValuesDescription
<run>string✅——Action run ID returned by createActionRun

Usage:

npx zapier-sdk get-action-run <run>

list-action-input-field-choices

Get the available choices for a dynamic dropdown input field

Options:

OptionTypeRequiredDefaultPossible ValuesDescription
<app>string✅——App slug (e.g., 'github'), implementation name (e.g., 'SlackCLIAPI'), or versioned ID (e.g., '[email protected]')
<action-type>string✅—read, read_bulk, write, run, search, search_or_write, search_and_write, filterAction type that matches the action's defined type
<action>string✅——Action key (e.g., 'send_message' or 'find_row')
<input-field>string✅——Input field key to get choices for
--connectionstring, 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.
--inputsobject❌——Current input values that may affect available choices
--pagenumber❌——Page number for paginated results
--page-sizenumber❌——Number of choices per page
--max-itemsnumber❌——Maximum total items to return across all pages
--cursorstring❌——Cursor to start from

Usage:

npx zapier-sdk list-action-input-field-choices <app> <action-type> <action> <input-field> [--connection] [--inputs] [--page] [--page-size] [--max-items] [--cursor]

list-action-input-fields

Get the input fields required for a specific action

Options:

OptionTypeRequiredDefaultPossible ValuesDescription
<app>string✅——App slug (e.g., 'github'), implementation name (e.g., 'SlackCLIAPI'), or versioned ID (e.g., '[email protected]')
<action-type>string✅—read, read_bulk, write, run, search, search_or_write, search_and_write, filterAction type that matches the action's defined type
<action>string✅——Action key (e.g., 'send_message' or 'find_row')
--connectionstring, 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.
--inputsobject❌——Current input values that may affect available fields
--page-sizenumber❌——Number of input fields per page
--max-itemsnumber❌——Maximum total items to return across all pages
--cursorstring❌——Cursor to start from

Usage:

npx zapier-sdk list-action-input-fields <app> <action-type> <action> [--connection] [--inputs] [--page-size] [--max-items] [--cursor]

list-actions

List all actions for a specific app

Options:

OptionTypeRequiredDefaultPossible ValuesDescription
<app>string✅——App key of actions to list (e.g., 'SlackCLIAPI' or slug like 'github')
--action-typestring❌—read, read_bulk, write, run, search, search_or_write, search_and_write, filterFilter actions by type
--page-sizenumber❌——Number of actions per page
--max-itemsnumber❌——Maximum total items to return across all pages
--cursorstring❌——Cursor to start from

Usage:

npx zapier-sdk list-actions <app> [--action-type] [--page-size] [--max-items] [--cursor]

run-action

Execute an action with the given inputs and wait for its results. Each result page includes the action run ID in meta.id.

Options:

OptionTypeRequiredDefaultPossible ValuesDescription
<app>string✅——App slug (e.g., 'github'), implementation name (e.g., 'SlackCLIAPI'), or versioned ID (e.g., '[email protected]')
<action-type>string✅—read, read_bulk, write, run, search, search_or_write, search_and_write, filterAction type that matches the action's defined type
<action>string✅——Action key (e.g., 'send_message' or 'find_row')
--connectionstring, 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.
--inputsobject❌——Input parameters for the action
--timeout-secondsnumber❌——Maximum time to wait for action completion in seconds (default: 180)
--idempotency-keystring❌——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.
--page-sizenumber❌——Number of results per page
--max-itemsnumber❌——Maximum total items to return across all pages
--cursorstring❌——Cursor to start from

Usage:

npx zapier-sdk run-action <app> <action-type> <action> [--connection] [--inputs] [--timeout-seconds] [--idempotency-key] [--page-size] [--max-items] [--cursor]

Apps

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.

get-app

Get detailed information about a specific app

Options:

OptionTypeRequiredDefaultPossible ValuesDescription
<app>string✅——App slug (e.g., 'github'), implementation name (e.g., 'SlackCLIAPI'), or versioned ID (e.g., '[email protected]')

Usage:

npx zapier-sdk get-app <app>

list-apps

List all available apps with optional filtering

Options:

OptionTypeRequiredDefaultPossible ValuesDescription
--searchstring❌——Search term to filter apps by name
--page-sizenumber❌——Number of apps per page. The upstream API may cap this and reject values above its limit.
--appsarray❌——Filter apps by app keys (e.g., 'SlackCLIAPI' or slug like 'github')
--max-itemsnumber❌——Maximum total items to return across all pages
--cursorstring❌——Cursor to start from

Usage:

npx zapier-sdk list-apps [--search] [--page-size] [--apps] [--max-items] [--cursor]

Client Credentials

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.

create-client-credentials

Create new client credentials for the authenticated user

Options:

OptionTypeRequiredDefaultPossible ValuesDescription
`<

版本与发布记录

@zapier/zapier-sdk-cli 共发布 312 个版本，首次发布于 2025/07/09；过去 12 个月发布了 266 个版本。

版本发布日期距今
0.89.3latest2026/11/03今天
0.89.22026/11/03今天
0.89.12026/11/03今天
0.89.02026/10/313 天前
0.88.02026/10/295 天前
0.87.42026/10/2212 天前

关于 @zapier/zapier-sdk-cli 的常见问题

@zapier/zapier-sdk-cli 是什么？

Zapier SDK的命令行接口

如何安装 @zapier/zapier-sdk-cli？

在项目目录运行 npm install @zapier/zapier-sdk-cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 zapier-sdk、zapier-sdk-cli、zapier-sdk-experimental，可以用 npx zapier-sdk 直接运行。

@zapier/zapier-sdk-cli 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

@zapier/zapier-sdk-cli 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require() 都可以使用，打包工具会自动选择合适的版本。

@zapier/zapier-sdk-cli 可以商用吗？

@zapier/zapier-sdk-cli 使用 SEE LICENSE IN LICENSE 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

@zapier/zapier-sdk-cli 还在维护吗？

最新版本 0.89.3 发布于 2026/11/03（今天）；至今共发布 312 个版本，其中过去 12 个月发布了 266 个；首次发布于 2025/07/09。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。