Migrate to Shopify CLI 4.
Shopify CLI 4.0 removes deprecated commands and flags, drops support for Node.js 20, and introduces automatic upgrades. Follow this guide to update an existing Shopify CLI 3.x installation and any scripts that use it.
Anchor to RequirementsRequirements
- Install Node.js 22.12 or higher, including in CI environments.
- Identify any scripts that run Shopify CLI commands, including package scripts and CI workflows.
Anchor to Step 1: Replace removed commands and flagsStep 1: Replace removed commands and flags
Update your scripts to use the following replacements:
| Removed in 4.0 | Replacement |
|---|---|
shopify webhook trigger | shopify app webhook trigger |
shopify theme serve | shopify theme dev |
shopify app generate schema | shopify app function schema |
shopify app scaffold extension | shopify app generate extension |
shopify app generate extension --type or -t | shopify app generate extension --template |
SHOPIFY_FLAG_EXTENSION_TYPE | SHOPIFY_FLAG_EXTENSION_TEMPLATE |
shopify app webhook trigger --shared-secret | shopify app webhook trigger --client-secret |
SHOPIFY_FLAG_SHARED_SECRET | SHOPIFY_FLAG_CLIENT_SECRET |
Anchor to Step 2: Choose deployment permissionsStep 2: Choose deployment permissions
The app deploy and app release commands no longer accept --force, -f, or SHOPIFY_FLAG_FORCE. Replace them with permissions that match the changes your pipeline needs to make:
| Required behavior | Flags |
|---|---|
| Allow updates without allowing deletions | --allow-updates |
| Allow updates and deletions without a confirmation prompt | --allow-updates --allow-deletes |
For guidance on avoiding accidental store data deletion, refer to Controlling extension and configuration deployment.
For example, if an unattended deployment uses --force, then replace it with the following command:
terminal
Add --allow-deletes only when your pipeline needs permission to delete app configuration or extensions. The app deploy --no-release flag continues to work and implicitly allows updates and deletions for the unreleased version.
Anchor to Step 3: Upgrade Shopify CLIStep 3: Upgrade Shopify CLI
Upgrade Shopify CLI with the package manager that you installed it with:
terminal
npm
npm install -g @shopify/cli@4yarn
yarn global add @shopify/cli@4pnpm
pnpm install -g @shopify/cli@4homebrew
brew upgrade shopify-cliThe npm, Yarn, and pnpm commands install the latest 4.x release. Homebrew upgrades to the latest available release.
For a project-local installation, update the project's @shopify/cli dependency and commit the lockfile. Update the version in CI workflows that install Shopify CLI directly.
Starting with 4.0, Shopify CLI upgrades itself automatically within the current major version. It doesn't upgrade automatically in CI environments or project-local installations, or when the next release changes the major version.
To turn off automatic upgrades, run:
terminal
To turn them on again, run shopify config autoupgrade on.
Anchor to Step 4: Verify your migrationStep 4: Verify your migration
Check the version from the directory where you run Shopify CLI:
terminal
Confirm that it reports 4.x. Check your package scripts and CI workflows for removed commands, flags, and environment variables. Run your usual development workflow with the updated installation.
Anchor to Next stepsNext steps
- Review the Shopify CLI 4.0 release notes.
- Look up current flags in the Shopify CLI command reference.