Shopify CLI

Shopify CLI is a command-line tool that helps you build Shopify themes faster. It automates and enhances your local development workflow with commands for working with themes on a Shopify store.

Overview

Shopify CLI comes bundled with a suite of commands for developing Shopify themes, including:

Creating, publishing, and deleting themes
Launching a development server for local theme development
Validating theme code with Theme Check
Managing theme files and assets

Installation

Follow the Shopify CLI installation guide for your operating system. Verify installation:

shopify version

Expected output:

Shopify CLI 3.x.x

Authentication

Authenticate with your Shopify Partner account:

shopify auth login

This opens a browser window for authentication. Once complete, you’ll see:

Logged in to Shopify
Partner organization: Your Org Name

Logout

Log out from your Shopify account:

shopify auth logout

Core Commands

Development Server

The most frequently used command during development.

shopify theme dev

What it does:

Uploads your local theme to a development theme on your store
Starts a local server at http://127.0.0.1:9292
Watches for file changes and syncs them automatically
Provides hot reload functionality
Injects hot reload script for instant updates

Output:

Uploading theme to development store...

Serving your theme at:
http://127.0.0.1:9292

Synced to development theme #123456789
https://your-store.myshopify.com/?preview_theme_id=123456789

Watching for changes...

Options:

# Use a specific store
shopify theme dev --store your-store.myshopify.com

# Use a different port
shopify theme dev --port 9293

# Use a specific theme
shopify theme dev --theme-id 123456789

# Disable hot reload
shopify theme dev --no-hot-reload

# Only watch specific files
shopify theme dev --only templates/product.liquid

Theme Check

Validate and lint your theme code.

shopify theme check

Output:

Checking theme...

✓ No issues found

Theme check complete!

Or with issues:

Checking theme...

sections/header.liquid:45:12
  LiquidTag: Unknown tag 'custom_tag'

templates/product.liquid:23:8
  ParserBlockingJavaScript: Avoid parser blocking JavaScript

2 issues found

Options:

# Check specific files
shopify theme check templates/product.liquid

# Check with auto-fix
shopify theme check --auto-correct

# Output JSON format
shopify theme check --output json

# List available checks
shopify theme check --list

Push Theme

Upload your local theme to your Shopify store.

shopify theme push

Interactive prompts:

Select a store:
1. your-store.myshopify.com
2. another-store.myshopify.com
> 1

Select theme to update:
1. Create new unpublished theme
2. Dawn (live theme)
3. Development theme
> 1

Uploading theme...
✓ Theme uploaded successfully
Theme ID: 123456789

Options:

# Push as unpublished theme
shopify theme push --unpublished

# Push to specific theme
shopify theme push --theme-id 123456789

# Push specific files
shopify theme push --only templates/product.liquid

# Ignore specific files
shopify theme push --ignore config/settings_data.json

# Allow live theme updates
shopify theme push --allow-live

Use --allow-live with caution. Pushing to a live theme affects your production site immediately.

Pull Theme

Download theme files from your Shopify store to your local machine.

shopify theme pull

Options:

# Pull from specific theme
shopify theme pull --theme-id 123456789

# Pull only specific files
shopify theme pull --only templates/

# Pull and ignore specific files
shopify theme pull --ignore config/settings_data.json

# Pull from live theme
shopify theme pull --live

Publish Theme

Make a theme the live theme on your store.

shopify theme publish

Interactive prompt:

Select theme to publish:
1. Horizon Development (ID: 123456789)
2. Test Theme (ID: 987654321)
> 1

Publishing theme...
✓ Theme is now live

Options:

# Publish specific theme by ID
shopify theme publish --theme-id 123456789

List Themes

Display all themes on your store.

shopify theme list

Output:

Themes on your-store.myshopify.com:

ID          NAME                ROLE
123456789   Dawn                live
987654321   Horizon Dev         unpublished
456789123   Development         development

Delete Theme

Remove a theme from your store.

shopify theme delete

Interactive prompt:

Select theme to delete:
1. Old Development (ID: 123456789)
2. Test Theme (ID: 987654321)
> 1

Are you sure you want to delete this theme? (y/n)
> y

Deleting theme...
✓ Theme deleted successfully

Options:

# Delete specific theme by ID
shopify theme delete --theme-id 123456789

# Delete development theme
shopify theme delete --development

Generate a shareable preview link for an unpublished theme.

shopify theme share

Output:

Generating preview link...

Share this link:
https://your-store.myshopify.com/?preview_theme_id=123456789&key=abc123def456

This link is valid for 14 days.

File Filtering

Many commands support --only and --ignore flags for selective file operations.

Using —only

Process only specific files or directories:

# Only templates
shopify theme push --only templates/

# Specific file
shopify theme push --only templates/product.liquid

# Multiple patterns
shopify theme push --only "templates/*.liquid" --only "sections/*.liquid"

Using —ignore

Exclude specific files or directories:

# Ignore settings data
shopify theme push --ignore config/settings_data.json

# Ignore multiple files
shopify theme push --ignore "*.json" --ignore "*.md"

Common Workflows

Starting Fresh Development

Clone and navigate to theme

git clone https://github.com/Shopify/horizon.git
cd horizon

Start development server

shopify theme dev

Make changes and validate

Edit files, then run:

shopify theme check

Deploying to Production

Run final validation

shopify theme check

Push as unpublished theme

shopify theme push --unpublished

Test the theme

Use the preview link to test thoroughly.

Publish when ready

shopify theme publish --theme-id 123456789

Syncing with Remote Changes

# Pull latest changes from live theme
shopify theme pull --live

# Or pull from specific theme
shopify theme pull --theme-id 123456789

Troubleshooting

Authentication Errors

shopify auth logout
shopify auth login

Port Already in Use

# Use a different port
shopify theme dev --port 9293

Theme Not Syncing

Check CLI output for errors
Verify file isn’t in .shopifyignore

Restart the development server:

# Press Ctrl+C to stop, then:
shopify theme dev

Conflicting Changes

If remote changes conflict with local changes:

# Pull remote changes
shopify theme pull

# Resolve conflicts in your editor
# Then push your changes
shopify theme push

Advanced Usage

Environment Variables

Set environment variables for automation:

# Set default store
export SHOPIFY_FLAG_STORE="your-store.myshopify.com"

# Set theme ID
export SHOPIFY_FLAG_THEME_ID="123456789"

# Then run commands without flags
shopify theme dev

CI/CD Integration

Use Shopify CLI in continuous integration:

# In your CI script
shopify theme check
shopify theme push --theme-id $THEME_ID --no-interactive

Next Steps

Theme Check

Deep dive into theme validation and linting

Development Workflow

Learn best practices for theme development

Official CLI Docs

Complete Shopify CLI documentation

Setup Guide

Set up your development environment

Overview

Core Concepts

Development

Customization

Features

Overview

Installation

Authentication

Logout

Core Commands

Development Server

Theme Check

Push Theme

Pull Theme

Publish Theme

List Themes

Delete Theme

File Filtering

Using —only

Using —ignore

Common Workflows

Starting Fresh Development

Deploying to Production

Syncing with Remote Changes

Troubleshooting

Authentication Errors

Port Already in Use

Theme Not Syncing

Conflicting Changes

Advanced Usage

Environment Variables

CI/CD Integration

Next Steps

Theme Check

Development Workflow

Official CLI Docs

Setup Guide

Build docs developers (and LLMs) love

Overview

Core Concepts

Development

Customization

Features

​Overview

​Installation

​Authentication

​Login

​Logout

​Core Commands

​Development Server

​Theme Check

​Push Theme

​Pull Theme

​Publish Theme

​List Themes

​Delete Theme

​Share Theme

​File Filtering

​Using —only

​Using —ignore

​Common Workflows

​Starting Fresh Development

​Deploying to Production

​Syncing with Remote Changes

​Troubleshooting

​Authentication Errors

​Port Already in Use

​Theme Not Syncing

​Conflicting Changes

​Advanced Usage

​Environment Variables

​CI/CD Integration

​Next Steps

Theme Check

Development Workflow

Official CLI Docs

Setup Guide

Build docs developers (and LLMs) love

Overview

Installation

Authentication

Login

Logout

Core Commands

Development Server

Theme Check

Push Theme

Pull Theme

Publish Theme

List Themes

Delete Theme

Share Theme

File Filtering

Using —only

Using —ignore

Common Workflows

Starting Fresh Development

Deploying to Production

Syncing with Remote Changes

Troubleshooting

Authentication Errors

Port Already in Use

Theme Not Syncing

Conflicting Changes

Advanced Usage

Environment Variables

CI/CD Integration

Next Steps