Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/shopdevs/multi-shop-cli

CLI tool for contextual development and automated shop management for multi-shop Shopify themes
https://github.com/shopdevs/multi-shop-cli

automation cli-tool developer-tools devops multi-shop nodejs shopify shopify-theme-development shopify-themes-maintenance theme-development typescript

Last synced: 2 days ago
JSON representation

CLI tool for contextual development and automated shop management for multi-shop Shopify themes

Awesome Lists containing this project

README 

          
# 🚀 Multi-Shop-CLI



[![CI](https://github.com/shopdevs/multi-shop-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/shopdevs/multi-shop-cli/actions/workflows/ci.yml)

[![npm version](https://img.shields.io/npm/v/@shopdevs/multi-shop-cli)](https://www.npmjs.com/package/@shopdevs/multi-shop-cli)

[![npm downloads](https://img.shields.io/npm/dm/@shopdevs/multi-shop-cli)](https://www.npmjs.com/package/@shopdevs/multi-shop-cli)

[![codecov](https://codecov.io/gh/shopdevs/multi-shop-cli/branch/main/graph/badge.svg)](https://codecov.io/gh/shopdevs/multi-shop-cli)

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)



> Contextual development and automated shop management for multi-shop Shopify

> themes



## What is Multi-Shop-CLI?



Transform any Shopify theme into a sophisticated multi-shop system with

**contextual development** that adapts to your branch context and **automated

shop syncing** that keeps all your stores in sync safely.



**Perfect for teams managing multiple Shopify stores** with Dawn theme, custom

themes, or any existing Shopify theme that needs multi-shop capabilities.



### ✨ Key Features



- **🧠 Contextual Development** - One command (`pnpm run dev`) adapts to your

  branch context

- **🤖 Automated Shop Syncing** - PRs auto-created when main updates

- **🔐 Secure Credentials** - Developer-specific tokens stored locally only

- **🎨 Shop Isolation** - Complete separation between shop customizations

- **⚡ Modern GitHub Flow** - Simple, PR-based development workflow

- **🧪 Interactive Testing** - Test against real Shopify preview themes



### 🛡️ Built-In Safeguards



- **🚨 Content Protection** (v2.3.0+) - Config-based prevention of content

  overwrites with strict/warn/off modes

- **🏥 Health Check** (v2.3.0+) - Comprehensive diagnostics for configuration,

  credentials, and branches

- **🎯 Campaign Tools** (v2.3.0+) - Automated campaign lifecycle management with

  one-command promo workflows

- **🔒 Security Audit** - `multi-shop audit` command checks permissions and

  credentials

- **✅ Tests** - Unit, integration, security, E2E, and performance tests

- **🌐 Cross-Platform** - Works on Windows, macOS, Linux (Node 18, 20, 22)

- **📚 Complete Docs** - API reference, guides, and working examples



---



## 🏁 Quick Start



### Installation



```bash

# Add to your theme project and initialize immediately

cd your-shopify-theme

pnpm add -D @shopdevs/multi-shop-cli && npx multi-shop init

```



This creates:



- `shops/` directory for shop configurations

- GitHub workflow for automated shop syncing

- Updated package.json with multi-shop-cli scripts

- Secure credential storage setup



### Set Up Your Shops



```bash

# Create all your shops interactively

pnpm run shop

# → Create New Shop



# For each shop, you'll configure:

# 1. Shop ID (e.g., fitness-store)

# 2. Display name (e.g., "Fitness Store")

# 3. Production domain (e.g., fitness-store.myshopify.com)

# 4. Staging domain (e.g., staging-fitness-store.myshopify.com)

# 5. Authentication method (theme-access-app recommended)



# Repeat for all shops:

# → shop-a (Shop A)

# → shop-b (Shop B)

# → shop-c (Shop C)

# → shop-d (Shop D)

```



### Start Development



```bash

# Use pnpm scripts (recommended)

pnpm run dev

# → Contextual development that adapts to your branch



# Or use npx directly

npx multi-shop dev

```



---



## 🚀 Complete Setup for Multiple Shops



Here's the step-by-step process to set up multi-shop-cli on a new Shopify theme

(example shows 4 shops, but you can use any number):



### Step 1: Initialize Project



```bash

cd your-shopify-theme

pnpm add -D @shopdevs/multi-shop-cli && npx multi-shop init

```



### Step 2: Create All 4 Shop Configurations



```bash

pnpm run shop

# → Create New Shop



# Shop A

# Shop ID: shop-a

# Name: Shop A

# Production: shop-a.myshopify.com

# Staging: staging-shop-a.myshopify.com

# Auth: theme-access-app



# Shop B

# Shop ID: shop-b

# Name: Shop B

# Production: shop-b.myshopify.com

# Staging: staging-shop-b.myshopify.com

# Auth: theme-access-app



# Shop C

# Shop ID: shop-c

# Name: Shop C

# Production: shop-c.myshopify.com

# Staging: staging-shop-c.myshopify.com

# Auth: theme-access-app



# Shop D

# Shop ID: shop-d

# Name: Shop D

# Production: shop-d.myshopify.com

# Staging: staging-shop-d.myshopify.com

# Auth: theme-access-app

```



### Step 3: Set Up Credentials (Each Developer)



Each developer needs to set up their own theme access tokens:



```bash

# Create credential files manually:

shops/credentials/shop-a.credentials.json

shops/credentials/shop-b.credentials.json

shops/credentials/shop-c.credentials.json

shops/credentials/shop-d.credentials.json

```



Example credential file format:



```json

// shops/credentials/shop-a.credentials.json

{

  "developer": "your-name",

  "shopify": {

    "stores": {

      "production": { "themeToken": "your-shop-a-production-password" },

      "staging": { "themeToken": "your-shop-a-staging-password" }

    }

  },

  "notes": "Theme access app credentials for shop-a"

}

```



### Step 4: GitHub Branches (Automated!)



When creating each shop, you'll be prompted:



```bash

# During shop creation:

# "Create GitHub branches for this shop?"

# → Yes, create branches automatically (Recommended)



# This automatically creates:

# shop-a/main and shop-a/staging

# shop-b/main and shop-b/staging

# shop-c/main and shop-c/staging

# shop-d/main and shop-d/staging



# If you chose "No" during setup, create manually:

git checkout -b shop-a/main && git push -u origin shop-a/main

git checkout -b shop-a/staging && git push -u origin shop-a/staging

# Repeat for other shops...

```



### Step 5: Connect Branches to Shopify Themes



For each shop, connect the Git branches to Shopify themes:



1. **Shopify Admin** → your-shop.myshopify.com → Online Store → Themes

2. **Add theme** → Connect from GitHub

3. **Select branch**: `shop-a/main` (for production) or `shop-a/staging`

4. **Repeat for all shops** (branches already created automatically!)



### Step 6: Verify Setup



```bash

# Check all shops are configured

pnpm run shop → List Shops

# Should show your configured shops (e.g., shop-a, shop-b, shop-c, shop-d)



# Check branches exist

git branch -r

# Should show: origin/shop-a/main, origin/shop-a/staging, etc.



# Check credential files exist (each developer)

ls shops/credentials/

# Should show your shop credential files (e.g., shop-a.credentials.json, shop-b.credentials.json)

```



### Step 7: Start Developing!



```bash

# Test contextual development

git checkout -b feature/new-header

pnpm run dev

# → Select shop for testing: shop-a, shop-b, shop-c, or shop-d

# → Select environment: staging (recommended) or production

# → Shopify CLI starts with selected shop's credentials



# Test different shops with same code

pnpm run dev  # Try different shop contexts

# Same feature code, different shop contexts!

```



---



## 🛠️ How It Works



### Contextual Development



The system detects your branch context and adapts automatically:



**Feature Branches** (like `feature/new-carousel`):



```bash

pnpm run dev

# → Prompts for shop context

# → Prompts for environment (staging/production)

# → Your code stays on feature branch

# → Testing happens against selected shop

```



**Shop Branches** (like `shop-a/custom-checkout`):



```bash

pnpm run dev

# → Auto-detects "shop-a"

# → Skips shop selection

# → Starts development immediately

```



### Automated Shop Syncing (GitHub Flow)



When you merge features to main:



1. **Use Tools → Sync Shops**: Select shops and create PRs

   `main → shop-*/staging`

2. **Each shop team reviews** their shop-specific PRs

3. **Shop teams create final PRs**: `shop-a/staging → shop-a/main`,

   `shop-b/staging → shop-b/main`, etc.



### Campaign Management (Per Shop) - v2.3.0+



**New Campaign Tools Menu** automates the entire campaign lifecycle:



```bash

# 1. Create promo branch (one command)

pnpm run shop → Campaign Tools → Create Promo Branch

# → Select shop: shop-a

# → Promo name: summer-sale

# → Automatically creates and pushes: shop-a/promo-summer-sale



# 2. Connect promo theme in Shopify admin

# → Add theme → Connect from GitHub → shop-a/promo-summer-sale



# 3. Customize in Shopify Theme Editor

# → Changes auto-sync back to promo branch



# 4. Launch promo

# → Publish theme or use Launchpad app



# 5. Push content back to main (one command)

pnpm run shop → Campaign Tools → Push Promo to Main

# → Select promo: shop-a/promo-summer-sale

# → Creates PR: shop-a/promo-summer-sale → shop-a/main



# 6. List all active campaigns

pnpm run shop → Campaign Tools → List Active Promos

# → Shows all promo branches across all shops



# 7. Clean up after campaign

pnpm run shop → Campaign Tools → End Promo

# → Select and delete finished promo branch

```



**Content Protection Integration:** Campaign content merges respect your Content

Protection settings, ensuring intentional content changes.



### Content Protection (v2.3.0+)



**Config-based safeguards** prevent accidental content overwrites:



```bash

# View protection status

pnpm run shop → Tools → Content Protection → Show Protection Status



# Configure individual shop

pnpm run shop → Tools → Content Protection → Configure Shop Protection

# → Select shop

# → Enable/Disable

# → Choose mode: strict (block), warn (confirm), or off

# → Choose verbosity: verbose or quiet



# Enable protection for all shops

pnpm run shop → Tools → Content Protection → Enable All Shops



# Configure global defaults

pnpm run shop → Tools → Content Protection → Global Settings

```



**Three Protection Modes:**



- **Strict** - Blocks cross-shop content syncs, requires 'OVERRIDE' to proceed

- **Warn** - Shows warning with file list, requires confirmation (default)

- **Off** - No protection, content syncs freely



**Smart Detection:** Distinguishes between risky cross-shop operations

(`main → shop-a`) and safe within-shop operations

(`shop-a/main → shop-a/staging`).



### Health Check (v2.3.0+)



**Diagnostic tool** verifies your shop configuration:



```bash

# Check single shop (detailed)

pnpm run shop → Tools → Health Check → Check Single Shop

# → Verifies: configuration, credentials, branches, content protection



# Check all shops (quick overview)

pnpm run shop → Tools → Health Check → Check All Shops

# → Shows status for every configured shop

```



**What it checks:**



- Configuration file validity (JSON, required fields, domains)

- Credentials existence, tokens presence, file permissions

- Git branch existence and sync status

- Content Protection status and settings



**Actionable recommendations** without auto-fixing - tells you exactly what

commands to run.



---



## 📋 Development Workflow



### Core Feature Development (GitHub Flow)



```bash

# 1. Create feature from main

git checkout main && git checkout -b feature/new-component



# 2. Contextual development

pnpm run dev  # Select shop context for testing



# 3. Test across shops

pnpm run dev  # Try different shop contexts



# 4. Sync with latest main (if needed)

pnpm run sync-main



# 5. Create PR directly to main (GitHub Flow)

gh pr create --base main --title "Add new component"



# 6. After merge → Auto-created shop sync PRs

```



### Shop-Specific Development



```bash

# 1. Create shop branch

git checkout shop-a/main

git checkout -b shop-a/custom-feature



# 2. Auto-detected development

pnpm run dev  # Auto-detects shop-a context



# 3. Create shop PR

gh pr create --base shop-a/main --title "Custom feature for Shop A"

```



---



## 🏗️ Architecture



### Branch Strategy



```

main (core theme)

├── feature/carousel-fix         # Contextual development

├── hotfix/critical-bug          # Emergency fixes

│

├── shop-a/main                  # Connected to shop-a

│   ├── shop-a/staging           # Connected to staging-shop-a

│   └── shop-a/promo-summer      # Campaign branches

│

├── shop-b/main                  # Connected to shop-b

│   ├── shop-b/staging           # Connected to staging-shop-b

│   └── shop-b/promo-holiday     # Campaign branches

│

├── shop-c/main                  # Connected to shop-c

│   └── shop-c/staging           # Connected to staging-shop-c

│

└── shop-d/main                  # Connected to shop-d

    └── shop-d/staging           # Connected to staging-shop-d

```



### Security Model



**Shop Configuration** (committed):



```json

// shops/shop-a.config.json

{

  "shopId": "shop-a",

  "name": "Shop A",

  "shopify": {

    "stores": {

      "production": {

        "domain": "shop-a.myshopify.com",

        "branch": "shop-a/main"

      },

      "staging": {

        "domain": "staging-shop-a.myshopify.com",

        "branch": "shop-a/staging"

      }

    },

    "authentication": {

      "method": "theme-access-app"

    }

  }

  // ⚠️ NO theme tokens stored here

}

```



**Developer Credentials** (local only):



```json

// shops/credentials/shop-a.credentials.json (NOT committed)

{

  "developer": "your-name",

  "shopify": {

    "stores": {

      "production": { "themeToken": "your-personal-production-password" },

      "staging": { "themeToken": "your-personal-staging-password" }

    }

  },

  "notes": "Theme access app credentials for shop-a"

}

```



---



## 🧪 Testing



### Interactive Testing with Real Themes



```bash

# Start dev server

pnpm run dev  # Get preview URL



# Run comprehensive tests

pnpm test:integration     # Shopping flow tests

pnpm test:visual         # Visual regression tests

pnpm test:accessibility  # WCAG compliance tests

pnpm test:performance    # Core Web Vitals tests



# Test shop sync PRs

pnpm run test:pr         # Comprehensive PR testing

```



All tests use **real Shopify preview themes** instead of mocks, providing

realistic testing conditions.



---



## 🔧 Troubleshooting



### Common Setup Issues



**"No shops configured yet"**



```bash

# Make sure you've created shop configurations:

pnpm run shop → Create New Shop

# Check: ls shops/ should show *.config.json files

```



**"No credentials found for shop-x"**



```bash

# Create credential file manually:

# shops/credentials/shop-x.credentials.json

# Get theme tokens from Shopify admin or theme access app

```



**"Shopify CLI not found"**



```bash

# Install Shopify CLI globally:

pnpm add -g @shopify/cli



# Verify installation:

shopify version

```



**"Permission denied" (Unix/Linux/macOS)**



```bash

# Fix credential file permissions:

chmod 600 shops/credentials/*.credentials.json

```



### Workflow Issues



**"Can't connect theme to GitHub branch"**



- Ensure branch exists: `git branch -r | grep shop-a/main`

- Check Shopify admin → Themes → Add theme → Connect from GitHub

- Verify repository connection in Shopify



**"Development server won't start"**



```bash

# Check your credentials and domain:

pnpm run shop → List Shops

# Verify tokens are correct in credential files

```



**"Feature branch not detecting context"**



```bash

# Check branch name pattern:

git branch --show-current

# Should be: feature/name or shop-a/name for auto-detection

```



**"Not sure what's wrong?" - Run Health Check (v2.3.0+)**



```bash

pnpm run shop → Tools → Health Check

# Comprehensive diagnostics with actionable recommendations

# Checks: config, credentials, branches, content protection

```



---



## 📚 Documentation



Comprehensive guides included:



- **Getting Started** - 5-minute setup

- **Contextual Development** - Core workflow innovation

- **Shop Management** - Creating and managing shops

- **Campaign Workflows** - Promo and content management

- **Testing Guide** - Interactive testing approach



---



## 🤝 Contributing



This package provides proven multi-shop workflow patterns for any Shopify theme

development team.



### Development



```bash

git clone https://github.com/shopdevs/multi-shop-cli.git

cd multi-shop-cli

pnpm install

pnpm test

```



### Publishing



```bash

npm version patch

npm publish

```



---



## 📄 License



MIT © [Brandt Milczewski](https://github.com/brandtam)



---



## 🙏 Acknowledgments



- Built for modern multi-shop Shopify development workflows

- Inspired by the need for better multi-shop Shopify development workflows

- Powered by [@clack/prompts](https://www.npmjs.com/package/@clack/prompts) for

  beautiful CLI experiences