Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
zapier-platform-cli (global install)
✓ npm install -g zapier-platform-cli
✗ npm install zapier-platform-cli
The CLI is intended for global installation to make the `zapier` or `zapier-platform` command available system-wide.
zapier command
✓ zapier-platform <command>
✗ zapier <command>
Since v18.0.0, the recommended executable name is `zapier-platform`, though `zapier` still works as a deprecated alias.
App Definition (Node.js)
✓ const App = require('./index'); // in test files or external scripts
module.exports = { /* ... App Definition ... */ }; // in index.js
✗ import App from './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.
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
zapier --version
Debug
Known issues
breakingThe 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.fixUpgrade 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. affects: >=18.0.0
breakingThe 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.fixUpdate all scripts, CI/CD pipelines, and local commands to use `zapier-platform` instead of `zapier`.
affects: >=18.0.0
breakingSpecific 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.fixIf 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.
affects: 18.0.2, 18.0.3, 18.0.4
breakingThe experimental flag `skipCleanArrayInputData` has been replaced with `cleanInputData` in `v18.0.0`. This impacts how data cleaning behavior is configured.fixMigrate configurations using `skipCleanArrayInputData` to the new `cleanInputData` flag, following the schema reference documentation.
affects: >=18.0.0
breakingUser 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.fixPlan 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.
affects: >=18.2.2
gotchaIntegrations 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.fixDecide 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.
affects: >=1.0.0
gotchaThe `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`.fixUpdate 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.
affects: >=18.0.6
Errors
Common errors & fixes
'zapier' is not recognized as an internal or external command, operable program or batch file.
The `zapier-platform-cli` package was not installed globally, or its installation directory is not in your system's PATH.
fixRun `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'.
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.
fixEnsure `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.
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.
fixVerify 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.
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.
fixRegularly 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`.
Audit
Dependencies
noderequiredRequired runtime environment, specifically Node.js >=18.20 for current versions of the CLI and generated apps.
zapier-platform-corerequiredCore library dependency for app definitions (triggers, actions, authentication). Automatically included in new projects generated by the CLI.