Shopify CLI

Common errors

• Error: The current Node.js version is X.Y.Z. Shopify CLI requires Node.js >= 20.10.0.

  cause The installed Node.js version does not meet the minimum requirement for Shopify CLI.
  fix Upgrade Node.js to version 20.10.0 or higher. Use `nvm install 20 && nvm use 20` or your preferred Node.js version manager.

• shopify: command not found

  cause The Shopify CLI executable is not in your system's PATH, or it was not installed globally.
  fix Ensure you have installed the CLI globally using `npm install -g @shopify/cli` or `yarn global add @shopify/cli` and that your npm/yarn global bin directory is included in your system's PATH.

• You are not logged in. Run "shopify login" to authenticate.

  cause The Shopify CLI is not authenticated with a Shopify partner account or a specific development store.
  fix Run `shopify login` to authenticate with your Shopify Partner account, or `shopify auth login --store your-store-name.myshopify.com` to authenticate with a specific development store.

• Error: EACCES: permission denied, mkdir '/Users/youruser/.shopify'

  cause Insufficient permissions to create necessary directories or files for the CLI's configuration or cache in your user home directory.
  fix Adjust permissions for the `.shopify` directory in your home folder. For example, `sudo chown -R $(whoami) ~/.shopify` can fix ownership issues. Avoid `chmod 777` unless you understand the security implications.

Warnings

• breaking The `shopify hydrogen init` command no longer supports the `--routes` flag. Routes are now automatically scaffolded by default during project initialization, removing the need for manual configuration via this flag.
  Fix: Remove the `--routes` flag from your `shopify hydrogen init` command invocations. Routes will be automatically generated as part of the new project setup.
• gotcha The Shopify CLI has a strict Node.js version requirement. Older Node.js versions (e.g., <20.10.0) are not supported and will prevent the CLI from running or cause unexpected behavior.
  Fix: Ensure your Node.js environment meets the minimum requirement of `>=20.10.0`. Use a Node.js version manager like `nvm` to easily switch and manage Node.js versions: `nvm install 20 && nvm use 20`.
• gotcha When re-authenticating using `shopify store auth`, existing granted scopes are now preserved by default. This change prevents unintended scope reductions during re-authentication, maintaining your app's existing permissions.
  Fix: Be aware that re-authenticating with `shopify store auth` will preserve your existing granted scopes. If you intend to modify scopes, ensure you understand the implications or consult the Shopify CLI documentation for advanced authentication options.
• gotcha The `shopify app dev` command now features an integrated Dev Console that renders directly within the Shopify admin interface. This changes the debugging and monitoring workflow by providing a more integrated experience.
  Fix: Familiarize yourself with the new Dev Console in the Shopify admin when using `shopify app dev` for debugging and monitoring your app's local development activities. Access it directly from your development store's admin panel.
• deprecated Older authentication patterns could lead to `401 Unauthorized errors` on cart AJAX endpoints during `shopify theme dev`. This issue has been addressed in recent CLI versions.
  Fix: Upgrade to Shopify CLI version 3.91.0 or newer to resolve `401 Unauthorized` errors on cart AJAX endpoints during theme development, as fixes for this issue were included in that release.

Install

• npm install shopify npm
• yarn add shopify yarn
• pnpm add shopify pnpm

Quickstart

This quickstart demonstrates how to initialize a new Shopify application using `shopify app init` and then run it locally with `shopify app dev`. It also outlines how to start theme development and deploy an app.

// Initialize a new Shopify application (e.g., Remix app with Hydrogen frontend)
// This command will guide you through setting up a new project.
// Replace 'my-shopify-app' with your desired project name.
// For non-interactive init, use 'shopify app init --name my-shopify-app --template remix --language typescript --verbose'
console.log("Initializing a new Shopify app...");
await new Promise(resolve => setTimeout(resolve, 1000)); // Simulate CLI delay
console.log("> shopify app init");
// Follow prompts to select app type (e.g., Shopify App), framework (e.g., Remix, Next.js), and language.
// After initialization, navigate into the project directory:
// cd my-shopify-app

console.log("\nStarting local development server for the app...");
await new Promise(resolve => setTimeout(resolve, 1000)); // Simulate CLI delay
console.log("> shopify app dev");
// This command starts a local development server, proxies requests to your app,
// and sets up tunneling for webhooks and redirects, allowing you to test your
// app directly against a Shopify development store. It also provides a Dev Console.

console.log("\nAlternatively, for theme development:");
await new Promise(resolve => setTimeout(resolve, 1000)); // Simulate CLI delay
console.log("> shopify theme init --store your-store-name.myshopify.com");
// This command will prompt you to select a theme from your store or create a new one.
// You can then develop it locally:
// cd your-theme-name
// shopify theme dev --store your-store-name.myshopify.com

console.log("\nTo deploy an app:");
await new Promise(resolve => setTimeout(resolve, 1000)); // Simulate CLI delay
console.log("> shopify app deploy");
// This command deploys your Shopify app to your partner account.