Troubleshooting Shopify App CLI

This reference guide contains information about upgrading, migrating from a legacy version, and uninstalling Shopify App CLI.

Upgrade Shopify API CLI

You can manage upgrades to Shopify App CLI with the package manager for your platform. You must use the same package manager to upgrade that you originally used to install Shopify App CLI.

Homebrew (macOS)

Terminal
$ brew update
$ brew upgrade shopify-cli

apt (Debian, Ubuntu)

  1. Download the latest .deb file for Shopify App CLI from the releases page.
  2. Install the downloaded file and make sure to replace /path/to/download/shopify-cli-x.y.z.deb with the path to your file's location:

    Terminal
    $ sudo apt install /path/to/downloaded/shopify-cli-x.y.z.deb

yum (CentOS 8+, Fedora, Red Hat, SUSE)

  1. Download the latest .rpm file for Shopify App CLI from the releases page.
  2. Install the downloaded file and make sure to replace /path/to/downloaded/shopify-cli-x.y.x.rpm with the path to your file's location.

    Terminal
    $ sudo yum install /path/to/downloaded/shopify-cli-x.y.x.rpm

RubyGems (macOS, Linux, Windows 10)

Terminal
$ gem update shopify-cli

Migrate from a legacy version

As of version 0.9.0, Shopify App CLI is installed and managed as a software package, instead of as a Git repository. If you’re using a legacy version, then you need to perform a one-time migration to keep using the CLI.

Complete the following steps to remove the legacy version and reinstall Shopify App CLI as a package:

  1. Check if you are using the legacy version.
  2. Uninstall the legacy Shopify App CLI.
  3. Install the new version.
  4. Re-authenticate the CLI.

Check if you are using the legacy version

You can determine if you’re using a legacy version by running the following command. If you get a command not found error, then you’re using a legacy version.

Terminal
$ shopify version

Uninstall the legacy Shopify App CLI

To uninstall a legacy version of Shopify App CLI, complete the following steps:

  1. Delete the legacy CLI files.
  2. Remove the legacy shopify command from your shell profile.
  3. Reload your terminal.

Delete the legacy CLI files

By default, Shopify App CLI was installed in your home directory. All the files are contained in a hidden directory called .shopify-app-cli. Run the following command to delete the directory:

Terminal
$ rm -rf ~/.shopify-app-cli/

Remove the legacy shopify command from your shell profile

During the install process, Shopify App CLI added a line to your shell configuration. This line could be located in one of the following files in your home directory:

  • ~/.bash_profile
  • ~/.zshrc
  • ~/.bash_login
  • ~/.profile
  • ~/.config/fish/config.fish

The line will look similar to one of the following examples. The exact syntax depends on your system. Deleting or commenting out the relevant line in your shell profile removes shopify as a command.

# 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

# The line might not be wrapped in an `if` statement. Example:
[ -f "/HOME_DIR/.shopify-app-cli/shopify.sh" ] && source "/HOME_DIR/.shopify-app-cli/shopify.sh"

Reload your terminal

For the changes made to your shell profile to take effect, exit your terminal, and start a new one.

  • If you try running shopify, then you should get a command not found error.
  • If you have the shopify_api gem installed, then you might see the following response:
shopify command is no longer bundled with shopify_api.
if you need these tools, install the shopify_cli gem

If so, then you also need to upgrade the shopify_api gem to v9.2.0+ to remove a deprecated shopify command that is contained in that gem.

If you also have the shopify_app gem (which depends on shopify_api gem), then you need to install or update shopify_api first, and then uninstall the older version.

To get a list of the version(s) of shopify_api currently installed, run the following command:

Terminal
$ gem list shopify_api

To install the latest version, run the following command:

Terminal
$ gem install shopify_api

To uninstall the older version, run the following command. Replace x.y.z with a version number listed from the gem list command. Repeat as needed.

Terminal
$ gem uninstall shopify_api -v x.y.z

Install the new version

After you've finished uninstalling the legacy version, you can install the most recent version of Shopify App CLI. Follow the installation instructions for your platform.

Re-authenticate the CLI

The migration process moves some configuration files, so you need to re-authenticate the CLI with your Shopify Partner dashboard. The CLI automatically prompts you to re-authenticate when needed.

Uninstall Shopify App CLI

Shopify App CLI can be removed from your system using the same package manager you used to install it.

Homebrew (macOS)

Terminal
$ brew uninstall shopify-cli

apt (Debian, Ubuntu)

Terminal
$ sudo apt remove shopify-cli

yum (CentOS 8+, Fedora, Red Hat, SUSE)

Terminal
$ sudo yum remove shopify-cli

RubyGems (macOS, Linux, Windows 10)

Terminal
$ gem uninstall shopify-cli

Uninstall a legacy version

If you’re using a legacy version of the CLI (<0.9.0), then you need to uninstall it manually.

Next steps