{"id":17078,"library":"zapier-platform-cli","title":"Zapier Platform CLI","description":"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.","status":"active","version":"18.5.0","language":"javascript","source_language":"en","source_url":"https://github.com/zapier/zapier-platform","tags":["javascript"],"install":[{"cmd":"npm install zapier-platform-cli","lang":"bash","label":"npm"},{"cmd":"yarn add zapier-platform-cli","lang":"bash","label":"yarn"},{"cmd":"pnpm add zapier-platform-cli","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required runtime environment, specifically Node.js >=18.20 for current versions of the CLI and generated apps.","package":"node","optional":false},{"reason":"Core library dependency for app definitions (triggers, actions, authentication). Automatically included in new projects generated by the CLI.","package":"zapier-platform-core","optional":false}],"imports":[{"note":"The CLI is intended for global installation to make the `zapier` or `zapier-platform` command available system-wide.","wrong":"npm install zapier-platform-cli","symbol":"zapier-platform-cli (global install)","correct":"npm install -g zapier-platform-cli"},{"note":"Since v18.0.0, the recommended executable name is `zapier-platform`, though `zapier` still works as a deprecated alias.","wrong":"zapier <command>","symbol":"zapier command","correct":"zapier-platform <command>"},{"note":"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.","wrong":"import App from './index.js'","symbol":"App Definition (Node.js)","correct":"const App = require('./index'); // in test files or external scripts\nmodule.exports = { /* ... App Definition ... */ }; // in index.js"}],"quickstart":{"code":"npm install -g zapier-platform-cli\n\n# Log in to your Zapier developer account\nzapier-platform login --sso # Use --sso if you log in via Google/SSO\n# Follow browser prompts or enter deploy key\n\n# Initialize a new Zapier integration project\nmkdir my-zapier-app\ncd my-zapier-app\nzapier-platform init . --template minimal\n\n# Install project dependencies\nnpm install\n\n# Add a simple 'hello world' trigger to src/index.js\n# Replace module.exports content with:\n# module.exports = {\n#   version: require('./package.json').version,\n#   platformVersion: require('zapier-platform-core').version,\n#   triggers: {\n#     hello_world: {\n#       key: 'hello_world',\n#       noun: 'Hello World',\n#       display: {\n#         label: 'New Hello World',\n#         description: 'Triggers when a new hello world event occurs.',\n#       },\n#       operation: {\n#         perform: () => [{\n#           id: 1,\n#           message: 'Hello, world!',\n#           createdAt: new Date().toISOString()\n#         }],\n#         sample: {\n#           id: 1,\n#           message: 'Hello, world!',\n#           createdAt: '2023-01-01T12:00:00Z'\n#         }\n#       },\n#     },\n#   },\n# };\n\n# Validate the project schema\nzapier-platform validate\n\n# Run local tests (if you have them, e.g., default ones)\nzapier-platform test\n\n# Register your app with Zapier (first time only)\nzapier-platform register\n\n# Push your integration to Zapier\nzapier-platform push","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=18.0.0"},{"fix":"Update all scripts, CI/CD pipelines, and local commands to use `zapier-platform` instead of `zapier`.","message":"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.","severity":"breaking","affected_versions":">=18.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":"18.0.2, 18.0.3, 18.0.4"},{"fix":"Migrate configurations using `skipCleanArrayInputData` to the new `cleanInputData` flag, following the schema reference documentation.","message":"The experimental flag `skipCleanArrayInputData` has been replaced with `cleanInputData` in `v18.0.0`. This impacts how data cleaning behavior is configured.","severity":"breaking","affected_versions":">=18.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=18.2.2"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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`.","severity":"gotcha","affected_versions":">=18.0.6"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"The `zapier-platform-cli` package was not installed globally, or its installation directory is not in your system's PATH.","error":"'zapier' is not recognized as an internal or external command, operable program or batch file."},{"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.","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.","error":"Error: `authentication` is undefined` or 'Project is Structurally Invalid'."},{"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.","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.","error":"API response 403 Forbidden during CLI testing/authentication."},{"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`.","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.","error":"npm WARN deprecated <package-name>@x.y.z: this library is no longer supported."}],"ecosystem":"npm","meta_description":null}