> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Shopify/horizon/llms.txt
> Use this file to discover all available pages before exploring further.

# Shopify CLI

> Complete guide to Shopify CLI commands and usage for Horizon theme development

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](https://shopify.dev/docs/storefronts/themes/tools/cli) for your operating system.

Verify installation:

```bash theme={null}
shopify version
```

Expected output:

```
Shopify CLI 3.x.x
```

## Authentication

### Login

Authenticate with your Shopify Partner account:

```bash theme={null}
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:

```bash theme={null}
shopify auth logout
```

## Core Commands

### Development Server

The most frequently used command during development.

```bash theme={null}
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:**

```bash theme={null}
# 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.

```bash theme={null}
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:**

```bash theme={null}
# 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.

```bash theme={null}
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:**

```bash theme={null}
# 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
```

<Warning>
  Use `--allow-live` with caution. Pushing to a live theme affects your production site immediately.
</Warning>

### Pull Theme

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

```bash theme={null}
shopify theme pull
```

**Options:**

```bash theme={null}
# 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.

```bash theme={null}
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:**

```bash theme={null}
# Publish specific theme by ID
shopify theme publish --theme-id 123456789
```

### List Themes

Display all themes on your store.

```bash theme={null}
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.

```bash theme={null}
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:**

```bash theme={null}
# Delete specific theme by ID
shopify theme delete --theme-id 123456789

# Delete development theme
shopify theme delete --development
```

### Share Theme

Generate a shareable preview link for an unpublished theme.

```bash theme={null}
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:

```bash theme={null}
# 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:

```bash theme={null}
# 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

<Steps>
  <Step title="Clone and navigate to theme">
    ```bash theme={null}
    git clone https://github.com/Shopify/horizon.git
    cd horizon
    ```
  </Step>

  <Step title="Start development server">
    ```bash theme={null}
    shopify theme dev
    ```
  </Step>

  <Step title="Make changes and validate">
    Edit files, then run:

    ```bash theme={null}
    shopify theme check
    ```
  </Step>
</Steps>

### Deploying to Production

<Steps>
  <Step title="Run final validation">
    ```bash theme={null}
    shopify theme check
    ```
  </Step>

  <Step title="Push as unpublished theme">
    ```bash theme={null}
    shopify theme push --unpublished
    ```
  </Step>

  <Step title="Test the theme">
    Use the preview link to test thoroughly.
  </Step>

  <Step title="Publish when ready">
    ```bash theme={null}
    shopify theme publish --theme-id 123456789
    ```
  </Step>
</Steps>

### Syncing with Remote Changes

```bash theme={null}
# Pull latest changes from live theme
shopify theme pull --live

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

## Troubleshooting

### Authentication Errors

```bash theme={null}
shopify auth logout
shopify auth login
```

### Port Already in Use

```bash theme={null}
# Use a different port
shopify theme dev --port 9293
```

### Theme Not Syncing

1. Check CLI output for errors
2. Verify file isn't in `.shopifyignore`
3. Restart the development server:
   ```bash theme={null}
   # Press Ctrl+C to stop, then:
   shopify theme dev
   ```

### Conflicting Changes

If remote changes conflict with local changes:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
# In your CI script
shopify theme check
shopify theme push --theme-id $THEME_ID --no-interactive
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Theme Check" icon="check" href="/development/theme-check">
    Deep dive into theme validation and linting
  </Card>

  <Card title="Development Workflow" icon="code" href="/development/workflow">
    Learn best practices for theme development
  </Card>

  <Card title="Official CLI Docs" icon="book" href="https://shopify.dev/docs/storefronts/themes/tools/cli">
    Complete Shopify CLI documentation
  </Card>

  <Card title="Setup Guide" icon="wrench" href="/development/setup">
    Set up your development environment
  </Card>
</CardGroup>