🚀 Multi-Shop-CLI

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

# 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

# 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

# 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

cd your-shopify-theme
pnpm add -D @shopdevs/multi-shop-cli && npx multi-shop init

Step 2: Create All 4 Shop Configurations

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:

# 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:

// 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:

# 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

# 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!

# 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):

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

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:

# 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:

# 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:

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

# 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

# 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):

// 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):

// 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

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

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

# Create credential file manually:
# shops/credentials/shop-x.credentials.json
# Get theme tokens from Shopify admin or theme access app

"Shopify CLI not found"

# Install Shopify CLI globally:
pnpm add -g @shopify/cli

# Verify installation:
shopify version

"Permission denied" (Unix/Linux/macOS)

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

# Check your credentials and domain:
pnpm run shop → List Shops
# Verify tokens are correct in credential files

"Feature branch not detecting context"

# 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+)

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

git clone https://github.com/shopdevs/multi-shop-cli.git
cd multi-shop-cli
pnpm install
pnpm test

Publishing

npm version patch
npm publish

---

📄 License

MIT © Brandt Milczewski

---

🙏 Acknowledgments

• Built for modern multi-shop Shopify development workflows
• Inspired by the need for better multi-shop Shopify development workflows
• Powered by @clack/prompts for beautiful CLI experiences