Getting started with Shopify CLI
Shopify CLI is a command-line interface tool that helps you build Shopify apps and themes. It quickly generates Node.js, Ruby on Rails, and PHP apps, app extensions, and Shopify themes. 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 app development, refer to Shopify CLI for apps.
Before you start
Anchor link to section titled "Before you start"Before you start using Shopify CLI to develop themes, make sure that you do the following tasks:
- Install Ruby or Ruby+Devkit using RubyInstaller for Windows (2.7 or higher).
- Install Git.
- If you want to use a development store to build a theme, then create or log in to a Shopify Partner account, and then create a development store.
- Make sure that you have a collaborator account or a staff account with the Manage themes permission or Themes permission for the store that you want to work on, or you're the owner of the store.
- Note the URL of the store that you want to work on.
- Make sure that you're connected to the internet. Most Shopify CLI commands need an internet connection to run.
Install Shopify CLI
Anchor link to section titled "Install Shopify CLI"Install Shopify CLI on macOS or Windows. For other platforms and package managers, refer to Install Shopify CLI.
macOS (Homebrew)
Anchor link to section titled "macOS (Homebrew)"
Windows (RubyGems.org)
Anchor link to section titled "Windows (RubyGems.org)"
Authenticate
Anchor link to section titled "Authenticate"Use shopify login
to connect Shopify CLI with the store that you want to work on.
You can log into a development store or a Shopify store. You need to have collaborator access to the store, or be a staff member or owner of the store. To switch between stores that you have access to, use shopify switch
.
In a terminal, type
shopify login --store <DOMAIN>
, where<DOMAIN>
is the store that you want to log into:In your browser window, log into the account that's attached to the store that you want to use for development.
Create a new theme
Anchor link to section titled "Create a new theme"Use shopify theme init
to create a new theme on your local machine. This command clones a Git repository to your local machine to use as the starting point for building a theme. By default, this command creates a copy of Dawn, Shopify's example theme.
To start cloning a theme, run the following command. You're prompted to enter a title for your theme, which also acts as the name of the directory.
Use an existing theme
Anchor link to section titled "Use an existing theme"If you want to use an existing local theme for development, then navigate to the theme's directory on your local machine using cd [path/to/theme]
. Any Shopify CLI theme command that you run uses the theme in that directory.
To use an existing remote theme, use one of the following options:
- Pull the theme onto your local machine using
shopify theme pull
. You're prompted to select a theme from the list of themes on the store. - If your theme is in GitHub, use
shopify theme init
and specify the remote URL using the--clone-url
flag.
Populate test data
Anchor link to section titled "Populate test data"Use shopify populate <object>
to populate your store with example data, such as products, customers, or draft orders, to test your theme's behavior.
To populate test data, run the following command, specifying the type of data that you want to add:
The output is similar to the following:
Preview, test, and share your theme
Anchor link to section titled "Preview, test, and share your theme"After you create or navigate to your theme, you can run shopify theme serve
to interact with the theme in a browser. Shopify CLI uploads the theme as a development theme on the store that you're connected to, and returns the following:
- A link to your development theme at http://127.0.0.1:9292. This URL can hot reload local changes to CSS and sections, or refresh the entire page when a file changes, allowing you to preview changes in real time using the store's data. This preview is available only in Google Chrome.
- A link to the editor for the theme in the Shopify admin.
- A preview link that you can share with others.
To serve your theme, run the following command:
The output is similar to the following:
Lint your theme's code
Anchor link to section titled "Lint your theme's code"Use shopify theme check
to analyze your code for errors and ensure that it follows theme and Liquid best practices. Learn more about the checks that Theme Check runs.
To run theme check against the current theme, run the following command.
The output is similar to the following:
Push your theme to your store
Anchor link to section titled "Push your theme to your store"Use shopify theme push
to upload your local theme files to Shopify, overwriting the remote versions. You're prompted to select the theme to overwrite from the list of the themes in your store. Use the --unpublished
flag to upload the theme to the theme library without overwriting an existing theme.
Publish your theme
Anchor link to section titled "Publish your theme"Use shopify theme publish
to select and publish an unpublished theme from your theme library. If you want to publish your local theme, then you need to run shopify theme push
first.
Find your theme ID
Anchor link to section titled "Find your theme ID"You might want to use a theme's ID to pull, push, publish, or delete a theme using Shopify CLI.
You can get the IDs of all of the themes in a store using shopify theme list
:
When you serve, push, or publish a theme, the theme's ID is listed in the response:
You can also find the ID of a theme in any URLs related to editing or previewing the theme:
Area | Example |
---|---|
Theme editor | https://johns-apparel.myshopify.com/admin/themes/THEME_ID/editor |
Code editor | https://johns-apparel.myshopify.com/admin/themes/THEME_ID |
Theme preview | https://johns-apparel.myshopify.com/?preview_theme_id=THEME_ID |
- Build and customize your themes faster using component-based Liquid examples.
- Use the Liquid Cheat Sheet as a quick reference while you build your themes.
- Access our comprehensive Liquid reference for detailed documentation on Liquid tags, objects, and filters.
- Read the complete reference documentation for core and theme-specific Shopify CLI commands.