Shopify CLI 2.x
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.
Running Shopify CLI 2.x and 3.x in the same environment
Anchor link to section titled "Running Shopify CLI 2.x and 3.x in the same environment"Shopify CLI 2.x and 3.x can be run in the same environment. CLI 2.x is run globally, while CLI 3.x is connected to specific projects. They also use a different base syntax, so they don’t conflict with one another.
Uninstall Shopify CLI 2.x and below
Anchor link to section titled "Uninstall Shopify CLI 2.x and below"To avoid confusion when using Shopify CLI 3.x, you can uninstall your previous version of Shopify CLI.
Install Shopify CLI 2.x
Anchor link to section titled "Install Shopify CLI 2.x"If you need to, you can install Shopify CLI 2.x. You should only install Shopify CLI 2.x if you are continuing work on an existing app that hasn't been migrated to Shopify CLI 3.x, or if Shopify CLI 2.x is explicitly specified in the prerequisites for a feature.
Upgrade Shopify CLI 2.x
Anchor link to section titled "Upgrade Shopify CLI 2.x"Until Shopify CLI 2.x is officially sunset, Shopify provides minor updates. Learn how to upgrade between minor versions of Shopify CLI 2.x.
Command overview
Anchor link to section titled "Command overview"Topic | Command | Description |
---|---|---|
Core | help | Lists the available commands and describes what they do. |
login | Authenticates and logs you into the specified store with Shopify CLI. | |
logout | Logs you out of the Shopify account or Partner account and store. | |
populate | Adds example data to your store for testing your app or theme’s behavior. | |
store | Displays the store that you're currently connected to. | |
switch | Switches between stores without logging out and logging in again. | |
version | Displays the version of Shopify CLI that you're running. | |
config | Configures Shopify CLI options. | |
whoami | Determines which Partner organization you're logged in to, or which store you're logged in to as a staff member. | |
app | create | Creates a project in a new subdirectory of the current directory. |
connect | Connects an existing Shopify CLI project to a Partner account or to a specific Shopify development store. | |
deploy | Deploys the current app to a hosting service. Currently, the only option is Heroku. | |
open | Opens your local development app in your default browser. | |
serve | Starts a local development server for your project, creates a public ngrok tunnel to your localhost, and updates your app URLs. | |
tunnel | Controls an HTTP tunnel to your local development app using ngrok. | |
extension | create | Generates a new extension project in a subdirectory of your app. To specify the type and name of your extension, you can use the interactive prompts or specify them as parameters on the command. |
serve | Starts a local server that can be rendered in the development store. | |
register | Creates your app extension and associates it with an app in your Partner organization. This step should be done only once for each app extension. | |
connect | Connects your local project directory to an existing app in your Partner organization. | |
push | Uploads your extension code to Shopify. | |
check | Runs Theme Check to analyze your code for errors and to ensure that it follows theme and Liquid best practices. |
Core commands
Anchor link to section titled "Core commands"Lists the available commands and describes what they do.
You can also use the help
command or options to get more detailed information about a specific command:
Authenticates and logs you into the specified store with Shopify CLI.
Optional parameters
Anchor link to section titled "Optional parameters"Parameter | Description |
---|---|
--store <DOMAIN> |
The store that you want to log in to. |
The --store
flag accepts the following inputs:
Type | Example |
---|---|
The store prefix | johns-apparel |
The myshopify.com URL | johns-apparel.myshopify.com https://johns-apparel.myshopify.com |
The store admin URL | https://johns-apparel.myshopify.com/admin |
To switch between stores that you have access to, use shopify switch
.
Logs you out of the Shopify account or Partner account and store.
The logout
command clears credentials. You need to reauthenticate the next time that you connect to a store.
Adds example data to your store for testing your app or theme’s behavior.
The populate
command lets you specify which type of data you're populating, and how many to create:
Parameter | Description |
---|---|
products |
Creates products in your store. Products are created with a title and a price. |
customers |
Creates customers in your store. Customers are created with a name only. |
draftorders |
Creates draft orders in your store. Draft orders are created with one custom item. |
--count <NUMBER> |
Creates the specified number of records. This is an optional parameter. If no count is specified, then five records are created. |
Displays the store that you're currently connected to.
Example output:
Switches between stores without logging out and logging in again.
If you enter this command without a --store
flag, then you're prompted to select a store associated with your account.
The --store
flag accepts the following inputs:
Type | Example |
---|---|
The store prefix | johns-apparel |
The myshopify.com URL | johns-apparel.myshopify.com https://johns-apparel.myshopify.com |
The store admin URL | https://johns-apparel.myshopify.com/admin |
Displays the version of Shopify CLI that you're running.
Example output:
Configures Shopify CLI options. There are two available options: analytics
and feature
.
Configures anonymous usage reporting by enabling or disabling analytics.
Configures active feature sets in the CLI.
This command is used for development and debugging work on the CLI tool itself. Unless you're developing the tool, don't alter this command. Review the Shopify CLI development guide for more information.
Determines which Partner organization you're logged in to, or which store you're logged in to as a staff member.
Example output:
App commands
Anchor link to section titled "App commands"This reference lists the Shopify CLI commands for apps. The basic syntax for these commands is shopify app <command>
.
To get help and tips from the command line, type a command with the flag -h
:
Creates a project in a new subdirectory of the current directory.
Specify one of the following frameworks in your command after create
:
After you enter the command, you're prompted to name your project.
Connects an existing Shopify CLI project to a Partner account or to a specific Shopify development store.
The connect
command creates the project's .env
and .shopify-cli.yml
files if they don't exist, or updates the files if they do exist.
.env
contains sensitive information that provides functionality to your app, such as the app key. As a result, this file shouldn't be saved to a version control system.shopify-cli.yml
contains insensitive information required for a project to work with Shopify CLI, such as the project type.
This command is useful if you're working on one project across multiple computers, or if you're collaborating with other developers using a version control system like Git.
Deploys the current app to a hosting service. Currently, the only option is Heroku.
Opens your local development app in your default browser.
Starts a local development server for your project, creates a public ngrok tunnel to your localhost, and updates your app URLs. You can override the app URL updates using the --no-update
flag.
You need to authenticate with ngrok using the shopify app tunnel auth
command before you run this command.
You need to create an ngrok account and auth token to preview your app using Shopify CLI.
Optional parameters
Anchor link to section titled "Optional parameters"Parameter | Description |
---|---|
--host=<URL> |
Bypass the tunnel and use a custom host. This value must be an HTTPS URL. |
--port=<PORT> |
Use a custom port. |
--no-update |
Don't update the App URLs that are set in the Partner Dashboard to use your ngrok URL. You might want to use this option if you're working on an app that's already deployed in one or more merchant stores. |
Controls an HTTP tunnel to your local development app using ngrok. With the tunnel
command, you can authenticate with ngrok and start or stop the tunnel.
To authenticate with ngrok, you need to create an ngrok account, and then create an authentication token from your ngrok dashboard. Copy your token and use it with the auth command:
To learn more about creating a token, refer to ngrok’s documentation.
You need to run this command before you start a new tunnel using the tunnel start
or serve
commands.
Start an ngrok tunnel to your app in your localhost development environment.
You need to authenticate with ngrok using the shopify app tunnel auth
command before you run this command.
You need to create an ngrok account and auth token to preview your app using Shopify CLI.
Stop the running ngrok tunnel:
Extension commands
Anchor link to section titled "Extension commands"This page lists Shopify CLI commands for creating, registering, and pushing app extensions.
Generates a new extension project in a subdirectory of your app. To specify the type and name of your extension, you can use the interactive prompts or specify them as parameters on the command.
Optional parameters
Anchor link to section titled "Optional parameters"Parameter | Description |
---|---|
--type <TYPE> |
The type of extension that you want to create. |
--name <NAME> |
The name of the extension. Shopify CLI transforms the input into snake case to name your directory. Extension names have a 50 character limit. |
Starts a local server that can be rendered in the development store. This command must be run from your extension’s directory. The server will continue to run until you press Ctrl
+C
.
In versions 1.11.0 and later, this command creates an HTTP tunnel to your local development extension using ngrok.
You need to authenticate with ngrok using the shopify app tunnel auth
command before you run this command.
You need to create an ngrok account and auth token to preview your app using Shopify CLI.
Optional parameters
Anchor link to section titled "Optional parameters"Parameter | Description |
---|---|
--tunnel |
Creates an HTTP tunnel (this is the default behavior). |
--no-tunnel |
Skips creating an HTTP tunnel. |
--resourceUrl |
A relative link to product or variant. To specify product, use --resourceUrl="products/12345" , where 12345 is the product ID. To specify a product variant, use --resourceUrl="products/12345/variants/4567" , where 12345 is the product ID and 4567 is the variant ID. If a specific resource URL isn't passed, then you're redirected to the details page of the first product in your shop. |
Upgrading dependencies
Anchor link to section titled "Upgrading dependencies"Serving the extension requires using an internal node module called @shopify/admin-ui-extensions-run
. Updating the CLI doesn't update the node modules automatically, so you might need to update this package manually. Run the following commands to update to the latest release:
Creates your app extension and associates it with an app in your Partner organization. This step should be done only once for each app extension.
Before you can push your code to Shopify, you need to create an app in your Partner Dashboard that you want to register your extension to. When you run this command, you're prompted to select an app from the list of apps in your Partner organization.
Connects your local project directory to an existing app in your Partner organization.
This command is intended to help teams collaborate on the same extension code.
Each developer can clone the extension code locally, and then run shopify extension connect
to populate the local .env
file with the client credentials required to push changes to the extension.
Uploads your extension code to Shopify. You need to run this command before you can publish your extension from the Partner Dashboard. You need to register your extension before you can push it to Shopify.
After a successful push, the CLI generates a link to the Partner Dashboard, where you can create a new version and publish your extension.
If you want to push your app extension to Shopify programmatically, then you can also pass your extension ID, client ID, and client secret as parameters with this command:
Learn more about running Shopify CLI in a CI/CD pipeline.
Optional parameters
Anchor link to section titled "Optional parameters"Parameter | Description |
---|---|
--extension-id |
The ID of your app extension. |
--api-key |
The client ID for your app, generated in the Partner Dashboard. |
--api-secret |
The client secret for your app generated in the Partner Dashboard. |