🚀 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.

$3

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

$3

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

$3

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

$3

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

`

$3

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

$3

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

$3

`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

`

$3

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"
}
`

$3

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

`

$3

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

$3

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

`

$3

`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

$3

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

`

$3

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.

$3

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.

$3

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

$3

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

$3

`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

`

$3

`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

$3

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

$3

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

$3

`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

$3

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

$3

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

$3

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

$3

`bash
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