Shopify App CLI helps you build Shopify apps faster. It automates many common tasks in the development process and lets you quickly add popular features, such as billing and webhooks.
⚠️ NOTE: This tool is currently a beta release in active development. Some features may be absent or incomplete, and functionality may change without warning. We welcome your feedback! Please check the contributing guide for notes on how to file bug reports and pull requests.
Shopify App CLI installs using a shell script. Download and run it in your terminal with one command:
eval "$(curl -sS https://raw.githubusercontent.com/Shopify/shopify-app-cli/master/install.sh)"
Install Linux Subsystem for Windows and the Ubuntu VM, then:
eval "$(curl -sS https://raw.githubusercontent.com/Shopify/shopify-app-cli/master/install.sh)"
NOTE: Installing the Shopify App CLI requires curl. You can to see if it's on your system by running:
curl --version
Developers should have some prior knowledge of the Shopify app ecosystem. Currently Shopify App CLI creates apps using either Node or Ruby.
- If you don’t have one, create a Shopify partner account.
- If you don’t have one, create a Development store where you can install and test your app.
- In the Partner dashboard, create a new app. You’ll need this app’s API credentials during the setup process. You can use any placeholder App URL when creating an app, then update it when your local development app is running.
NOTE: A future release will allow you to provision API credentials and development stores without leaving the CLI. During the beta, it must be done through the Partner Dashboard.
When creating a new app with the Partner Dashboard, you’ll need to provide a few URLs for your app, which allow it to authenticate and embed in the Shopify admin. Once your local development app is running (using shopify serve
), you’ll need to update these URLs with your live ngrok URLs.
Edit your app’s whitelisted redirection URLs in the Partner Dashboard by navigating to Apps > [Your app name] > App setup. On the App setup screen, set “App URL” to your live ngrok URL. Add the following two URLs to the “Whitelisted redirection URLs” field:
For Node.js Apps:
https://<LIVE_NGROK_URL>/auth/callback
http://localhost:3456
For Rails Apps:
https://<LIVE_NGROK_URL>/auth/shopify/callback
http://localhost:3456
The first URL handles the authentication flow for adding your app to a Shopify development store. The second is currently necessary to allow your local development server to make Shopify API requests on behalf of your development app.
NOTE: A future release will handle this URL whitelisting process automatically. During the beta, it must be done through the Partner Dashboard.
The create
command will scaffold a new Shopify app in your current active directory and generate all the necessary starter files.
$ shopify create project APP_NAME
The CLI will ask what type of app you want to create. Two languages are currently supported:
- Node.js and React
- Ruby
The CLI will also ask for your app’s API key and API secret, which you can find in your Partner Dashboard (see “Requirements” above).
Running the serve
command in your app directory will start your local development server as well as a public tunnel to your local development app (see the tunnel
command below). This will make your app visible to anyone with the ngrok URL.
$ shopify serve
Your terminal will display the localhost and port where your app is now visible.
Use tunnel
to set up a public tunnel to your local app. Shopify App CLI uses ngrok to manage this connection. Starting a tunnel will make your app visible to anyone with the ngrok URL.
$ shopify tunnel start
Use the stop
command to close the tunnel:
$ shopify tunnel stop
As the Shopify App CLI creates an embedded app, you'll need to install it on a development store. To do so, open the installation URL in your web browser: https://<LIVE_NGROK_URL>/auth?shop=your-development-store.myshopify.com
. This will prompt you to install on your development store. It’s necessary to view and test your app in a live development store because some App Bridge and Polaris features are only available for use by your app when it’s embedded in the Shopify admin.
Shopify App CLI automates several common developer tasks. Currently generate
supports the following actions:
- Generating new pages in your app
- Generating new billing models and endpoints
- Generating new webhooks to listen for store events
$ shopify generate page PAGE_NAME
The CLI will scaffold the new page in the pages
directory.
$ shopify generate billing
The CLI will ask whether you want to create a one-time billing model or a recurring subscription model.
Webhooks allow your app to listen for events that happen on any stores that have it installed. The CLI can quickly register a new webhook for any valid store event.
$ shopify generate webhook WEBHOOK_NAME
A list of supported webhook events is available in Shopify’s API docs.
Developers can use development stores to test their apps. Development stores have no products, customers or orders when they’re created. Shopify App CLI can quickly add dummy data to your development store so you can test your app more thoroughly.
The populate
command can add fake products, customers, and orders. The default number of items added is 10. You can specify a different number of items with the --count
option.
# Adds 10 fake products
$ shopify populate products
# Adds 10 fake customers
$ shopify populate customers
# Adds 25 fake orders
$ shopify populate orders --count 25
$ shopify update
The update
command will upgrade your production instance of the CLI to use the most recent version.
This is an open-source tool and developers are invited to contribute to it. Please check the code of conduct and the design guidelines before you begin.
Developing Shopify App CLI often requires having multiple instances of the tool installed for testing purposes. There are two commands that give developers greater control over their Shopify App CLI environment:
# Clone the repo for development purposes
$ git clone [email protected]:Shopify/shopify-app-cli.git
# Configure the CLI to use your development instance
$ shopify load-dev `/path/to/instance`
The load-dev
command loads the version of Shopify App CLI specified between the backticks.
$ shopify load-system
The load-system
command resets the CLI to use the production instance.
A Vagrantfile is provided with some images for testing cross-platform. For more information see the Vagrant docs. Here's how to test the install script on Ubuntu.
$ vagrant up ubuntu
$ vagrant ssh ubuntu
vagrant$ cd /vagrant
vagrant$ eval "$(cat install.sh)"
You can run rake console
inside this repo to interact with the CLI's ruby API inside of an irb
console.
rake console
irb(main):001:0> ShopifyCli::ROOT
=> "/Users/me/src/github.com/Shopify/shopify-cli"
There are two steps to completely uninstall Shopify App CLI:
- Delete the CLI files.
- Remove the
shopify
command from your shell profile.
With the standard installation process, Shopify App CLI is installed in your home directory. All the files are contained in a hidden directory called .shopify-app-cli
, which you can delete to uninstall.
During the install process, Shopify App CLI adds a line to your shell configuration. This line is typically located in the .bash_profile
file in your home directory (depending on your system, it may also be found in .bash_login
or .profile
). It will look similar to this:
# The line won’t look exactly like this. `HOME_DIR` will instead be the absolute path to your home directory
if [[ -f /HOME_DIR/.shopify-cli/shopify.sh ]]; then source /HOME_DIR/.shopify-cli/shopify.sh; fi
Deleting or commenting out this line will remove shopify
as a command. You may need to reload your shell.