Shopify CLI for themes
Shopify CLI is a command-line interface tool that helps you build Shopify apps and themes. It quickly generates Shopify apps, themes, and custom storefronts. You can also use it to automate many common development tasks.
This documentation explains how to use Shopify CLI for theme development. To learn how to use Shopify CLI for other tasks, refer to the following documentation:
Choosing between Shopify CLI and Theme KitAnchor link to section titled "Choosing between Shopify CLI and Theme Kit"
Shopify CLI replaces Theme Kit for most Shopify theme development tasks. You should use Shopify CLI if you're working on Online Store 2.0 themes. You should use Theme Kit instead of Shopify CLI only if you're working on older themes.
Shopify CLI accelerates your theme development process with the following features:
- Safely preview, test, and share changes to themes using development themes
- Hot reload CSS and section changes, or automatically refresh a page on file change, when previewing a theme
- Initialize a new theme using Dawn as a starting point
- Push and publish themes from the command line
- Run Theme Check on your theme
Development themesAnchor link to section titled "Development themes"
Development themes are temporary, hidden themes that are connected to the Shopify store that you're using for development. When you connect your theme to a store as a development theme, you can use that store's data for local testing.
You can create a development theme using the
shopify theme dev command.
You can use development themes on a Shopify store or a development store. Development themes don't count toward your theme limit, and are deleted from the store after seven days of inactivity.
Your development theme is deleted when you run
shopify auth logout. If you want a preview link for the theme that can be accessed after you log out, then you should push your development theme to an unpublished theme on your store.
Your development theme can be used to perform the following tasks:
- View changes in real time to a theme that you're developing locally
- Customize and interact with the theme using the Shopify admin theme editor
- Share a password-protected preview of the theme with other developers
InstallationAnchor link to section titled "Installation"
To learn how to install Shopify CLI on Windows, macOS, or Linux, refer to Install Shopify CLI.
Getting startedAnchor link to section titled "Getting started"
Refer to the following tutorials for details about creating or working on a Shopify theme using Shopify CLI:
Command referenceAnchor link to section titled "Command reference"
Refer to the Shopify CLI theme command reference to explore the commands available to build themes with Shopify CLI.
Authenticating and accessing storesAnchor link to section titled "Authenticating and accessing stores"
As a theme developer, you might want to use a Shopify store to test your theme, or to share your theme with stakeholders. You also might need to work on multiple stores, or use a different set of credentials to authenticate with a particular store. Learn about the authentication methods that you can use to work on stores using Shopify CLI, and how to switch between accounts and stores.
AuthenticationAnchor link to section titled "Authentication"
You can use two authentication methods to work on a theme in a Shopify store using Shopify CLI:
- Log in with a Shopify account
- Provide a Theme Access password
Log in with a Shopify accountAnchor link to section titled "Log in with a Shopify account"
You can use the following types of Shopify accounts to access the store you want to work on:
- A collaborator account with the Manage themes permission
- A staff account with the Themes permission
- The store owner account
To authenticate with a Shopify account, run a command that requires store access. You'll be prompted to log in.
Switching between accountsAnchor link to section titled "Switching between accounts"
If you need to switch between accounts, then log out of the current account using the following command:
The next time you enter a command that requires authentication, you'll be prompted to log in, and can enter a new set of credentials.
Theme Access passwordAnchor link to section titled "Theme Access password"
You can use a Theme Access password to authenticate with the store that you want to work on. Theme Access passwords are generated for a store using the Theme Access app.
To use a Theme Access password, pass the
--password flag with each command that you want to run against the store. If you run a command without the
--password flag, then Shopify CLI attempts to use your Shopify account credentials to run the command.
Connecting to a storeAnchor link to section titled "Connecting to a store"
The first time you enter a command that requires you to interact with a Shopify store, pass the
--store flag with the command and specify the store that you want to interact with:
The store that you specify is used for future commands until a new store is specified.
If you want to change the store that you're interacting with, pass the
--store flag with your command, specifying the new store that you want to interact with.
To check which store you're using, run
shopify theme info:
Directory structureAnchor link to section titled "Directory structure"
You can run certain theme commands, such as
shopify theme dev, only if the directory you're using matches the default Shopify theme directory structure. This structure represents a buildless theme, or a theme that has already gone through any necessary file transformations. If you use build tools to generate theme files, then you might need to run commands from the directory where the generated files are stored.
The default Shopify theme directory structure is as follows:
Excluding files from Shopify CLIAnchor link to section titled "Excluding files from Shopify CLI"
If you have files in the same repository as your theme that you don't want to interact with using Shopify CLI, then you can add them to a
.shopifyignore at the root of the theme.
.shopifyignore accepts references to files in the following formats:
- Simple file names:
- Regular expressions:
You can also exclude specific files or patterns during a
pull using the
--ignore flag. If files are excluded using
.shopifyignore, then both the contents of
.shopifyignore and the
--ignore flag are respected.
Using Shopify CLI for continuous integrationAnchor link to section titled "Using Shopify CLI for continuous integration"
If you have a theme that you want to work with programmatically, then you can integrate Shopify CLI into your CI/CD pipeline to perform actions like pushing, pulling, and publishing a theme.
Upgrade Shopify CLIAnchor link to section titled "Upgrade Shopify CLI"
To upgrade Shopify CLI 3.x to the latest version, use the
To check your CLI version, use the
Migrate to Shopify CLI 3.xAnchor link to section titled "Migrate to Shopify CLI 3.x"
In October 2022, support for themes was added to Shopify CLI 3.x. Shopify CLI 3.x provides a streamlined authentication and store management experience.
To learn about the differences between Shopify CLI 2.x and 3.x, how to upgrade to Shopify CLI 3.x, or how to use both Shopify CLI 2.x and 3.x on the same machine, refer to Migrate to Shopify CLI 3.x.
Usage reportingAnchor link to section titled "Usage reporting"
Anonymous usage statistics are collected by default. To opt out, you can use the environment variable
Contributing to Shopify CLIAnchor link to section titled "Contributing to Shopify CLI"
Shopify CLI is open source. Learn how to contribute to our GitHub repository.
Where to get helpAnchor link to section titled "Where to get help"
- Open a GitHub issue - To report bugs or request new features, open an issue in the Shopify CLI repository.
- Shopify Community Forums - Visit our forums to connect with the community and learn more about Shopify CLI development.