Zapier Platform CLI

18.5.0 · active · verified Wed Apr 22

The Zapier Platform CLI is a command-line interface tool that enables developers to build, test, and deploy custom integrations for the Zapier Developer Platform. It provides a code-first approach to creating Zapier apps, allowing for advanced customization of API interactions, authentication flows, triggers, actions, and searches. This CLI is particularly suited for development teams leveraging version control and CI/CD pipelines, offering greater control than the browser-based Platform UI. The current stable version is 18.5.0, with frequent minor releases providing continuous improvements and bug fixes. Developers primarily write Node.js applications that export a defined schema, which Zapier then introspects to understand the app's capabilities. Integrations built with the CLI run on AWS Lambda, utilizing standard Node.js libraries and a specific `zapier-platform-core` dependency for platform interaction.

Common errors

```
'zapier' is not recognized as an internal or external command, operable program or batch file.
```
cause The `zapier-platform-cli` package was not installed globally, or its installation directory is not in your system's PATH.

fix Run `npm install -g zapier-platform-cli` to install the CLI globally. If the issue persists, verify that npm's global bin directory is included in your system's PATH environment variable.
```
Error: `authentication` is undefined` or 'Project is Structurally Invalid'.
```
cause Commonly occurs when the `authentication` object in `index.js` is not correctly imported or exported, or its structure does not conform to the Zapier Platform schema.

fix Ensure `index.js` exports the `authentication` property correctly, often as `module.exports = { authentication: require('./authentication'), ... };` or by defining it directly within `module.exports`. Check Zapier's schema reference for the expected `authentication` object structure.
```
API response 403 Forbidden during CLI testing/authentication.
```
cause Incorrect API key/client ID, missing environment variables, API endpoint configuration (e.g., IP whitelist, missing User-Agent header), or rate limiting by the target API.

fix Verify all environment variables (`process.env.API_KEY`, etc.) are correctly set (e.g., in `.env` file for local testing). Check the API documentation for required headers like `User-Agent` and ensure the CLI's requests are not blocked by IP restrictions. Enable verbose logging with `zapier-platform --debug` for more details.
```
npm WARN deprecated <package-name>@x.y.z: this library is no longer supported.
```
cause The Zapier Platform CLI or its underlying dependencies (or your integration's dependencies) are using outdated packages with known deprecation warnings, sometimes indicating security vulnerabilities.

fix Regularly update `zapier-platform-cli` to the latest version (`npm install -g zapier-platform-cli@latest`). For your integration's dependencies, run `npm audit` and `npm update` to address vulnerabilities and deprecated packages, ensuring compatibility with `zapier-platform-core`.

Warnings

breaking The Zapier Platform CLI and generated apps now require Node.js v18.20 or newer. Older Node.js versions may lead to compatibility issues or deployment failures.
Fix: Upgrade your local Node.js environment to v18.20 or higher, using tools like `nvm` if managing multiple versions. Ensure `package.json` specifies `engines: {"node": ">=18.20"}` and `zapier-platform-core` is updated to a compatible version.
breaking The CLI executable name `zapier` has been deprecated in favor of `zapier-platform`. While `zapier` still works as an alias, `zapier-platform` is the recommended command.
Fix: Update all scripts, CI/CD pipelines, and local commands to use `zapier-platform` instead of `zapier`.
breaking Specific versions of `zapier-platform-cli` (18.0.2, 18.0.3, 18.0.4) and `zapier-platform-core` were affected by an npm supply chain compromise in late 2025. These packages should not be used.
Fix: If you have downloaded any affected packages, immediately run `npm cache clean --force`, delete `node_modules` and `package-lock.json`, and reinstall `zapier-platform-cli@latest` and `zapier-platform-core@latest` to ensure you are using unaffected versions.
breaking The experimental flag `skipCleanArrayInputData` has been replaced with `cleanInputData` in `v18.0.0`. This impacts how data cleaning behavior is configured.
Fix: Migrate configurations using `skipCleanArrayInputData` to the new `cleanInputData` flag, following the schema reference documentation.
breaking User migrations between major versions of an integration (e.g., from 1.x.x to 2.x.x) are now blocked by both the Platform UI and CLI.
Fix: Plan for major version upgrades by communicating with users to manually update their Zaps, or consider providing deprecated versions for a transition period. Only minor version migrations are supported for automatic user transfers.
gotcha Integrations created or managed via the Zapier Platform CLI cannot be fully edited in the Zapier Platform UI. Only core details and monitoring can be managed visually; code-level changes must be done via the CLI.
Fix: Decide early in development whether to use the CLI or UI for an integration, as switching between the two for core development is not straightforward. CLI apps are best for code-centric teams.
gotcha The `zapier build` command (and `zapier-platform build`) now detects the project's package manager (`npm`, `yarn`, `pnpm`) from `packageManager` field or lock files. The `--skip-npm-install` flag has been renamed to `--skip-dep-install`.
Fix: Update CI/CD scripts and local workflows to use `--skip-dep-install` if dependency installation needs to be skipped during the build process. Ensure `packageManager` field is correctly set if relying on a specific package manager other than npm.

Install

npm install zapier-platform-cli npm
yarn add zapier-platform-cli yarn
pnpm add zapier-platform-cli pnpm

Imports

zapier-platform-cli (global install)
wrong:
```
npm install zapier-platform-cli
```
correct:
```
npm install -g zapier-platform-cli
```
The CLI is intended for global installation to make the `zapier` or `zapier-platform` command available system-wide.
zapier command
wrong:
```
zapier <command>
```
correct:
```
zapier-platform <command>
```
Since v18.0.0, the recommended executable name is `zapier-platform`, though `zapier` still works as a deprecated alias.
App Definition (Node.js)
wrong:
```
import App from './index.js'
```
correct:
```
const App = require('./index'); // in test files or external scripts
module.exports = { /* ... App Definition ... */ }; // in index.js
```
Zapier CLI apps use CommonJS modules (`module.exports`, `require`) for the main app definition file (`index.js`). ESM is supported internally but the primary app structure is CJS.

Quickstart

This quickstart demonstrates how to set up the Zapier Platform CLI, log into your Zapier account, initialize a new integration project, add a minimal 'Hello World' trigger, validate the app, run tests, and finally deploy the integration to the Zapier Developer Platform.

npm install -g zapier-platform-cli

# Log in to your Zapier developer account
zapier-platform login --sso # Use --sso if you log in via Google/SSO
# Follow browser prompts or enter deploy key

# Initialize a new Zapier integration project
mkdir my-zapier-app
cd my-zapier-app
zapier-platform init . --template minimal

# Install project dependencies
npm install

# Add a simple 'hello world' trigger to src/index.js
# Replace module.exports content with:
# module.exports = {
#   version: require('./package.json').version,
#   platformVersion: require('zapier-platform-core').version,
#   triggers: {
#     hello_world: {
#       key: 'hello_world',
#       noun: 'Hello World',
#       display: {
#         label: 'New Hello World',
#         description: 'Triggers when a new hello world event occurs.',
#       },
#       operation: {
#         perform: () => [{
#           id: 1,
#           message: 'Hello, world!',
#           createdAt: new Date().toISOString()
#         }],
#         sample: {
#           id: 1,
#           message: 'Hello, world!',
#           createdAt: '2023-01-01T12:00:00Z'
#         }
#       },
#     },
#   },
# };

# Validate the project schema
zapier-platform validate

# Run local tests (if you have them, e.g., default ones)
zapier-platform test

# Register your app with Zapier (first time only)
zapier-platform register

# Push your integration to Zapier
zapier-platform push

view raw JSON →