Shopify App CLI

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.

Table of Contents

• Install
• Getting started
• Commands
• Contributing to development
• Uninstall

Install

Shopify App CLI installs using a shell script. Download and run it in your terminal with one command:

Mac OS and Ubuntu

eval "$(curl -sS https://raw.githubusercontent.com/Shopify/shopify-app-cli/master/install.sh)"

Windows

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

Getting started

Developers should have some prior knowledge of the Shopify app ecosystem. Currently Shopify App CLI creates apps using either Node or Ruby.

Requirements

• 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.
• You should have Node.js version 10.0.0 or higher installed. If you're looking for a way to manage your node versions we recommend nvm

Commands

Create a new app project

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).

Start a development server

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. Your app can then be installed on a development store from your Partner Dashboard.

Start or stop a tunnel to your localhost

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

Loading your app within the admin

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 with shopify open. 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.

Generate new app features

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

Create a new page

$ shopify generate page PAGE_NAME

The CLI will scaffold the new page in the pages directory. In node apps, you can view this page by appending the name you pass to the url.

Create a billing model

$ shopify generate billing

The CLI will ask whether you want to create a one-time billing model or a recurring subscription model.

Create a new webhook

Webhooks allow your app to listen for events that happen on any stores that have them 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.

Add test data to a development store

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 draftorders. The default number of items added is 5. You can specify a different number of items with the --count option.

# Adds 5 fake products
$ shopify populate products

# Adds 5 fake customers
$ shopify populate customers

# Adds 25 fake orders
$ shopify populate draftorders --count 25

Update to the latest version

$ shopify update

The update command will upgrade your production instance of the CLI to use the most recent version.

Developing Shopify App CLI

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:

Load a development instance

# Clone the repo for development purposes
$ git clone git@github.com: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.

Reload the production instance

$ shopify load-system

The load-system command resets the CLI to use the production instance.

VM testing

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)"

Ruby console

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"

Uninstalling Shopify App CLI

There are two steps to completely uninstall Shopify App CLI:

1. Delete the CLI files.
2. Remove the shopify command from your shell profile.

Delete the CLI files

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.

Remove the shopify command from your shell

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.