{"id":49434319,"url":"https://github.com/shopdevs/multi-shop-cli","last_synced_at":"2026-04-29T16:10:17.307Z","repository":{"id":321287873,"uuid":"1052310653","full_name":"shopdevs/multi-shop-cli","owner":"shopdevs","description":"CLI tool for contextual development and automated shop management for multi-shop  Shopify themes","archived":false,"fork":false,"pushed_at":"2026-01-12T20:03:43.000Z","size":287,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-13T00:48:21.458Z","etag":null,"topics":["automation","cli-tool","developer-tools","devops","multi-shop","nodejs","shopify","shopify-theme-development","shopify-themes-maintenance","theme-development","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@shopdevs/multi-shop-cli","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shopdevs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["brandtam"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":null}},"created_at":"2025-09-07T20:37:37.000Z","updated_at":"2026-01-12T20:03:47.000Z","dependencies_parsed_at":null,"dependency_job_id":"8e38abd4-5bb6-44b8-a387-3cd1862f6cfa","html_url":"https://github.com/shopdevs/multi-shop-cli","commit_stats":null,"previous_names":["shopdevs/multi-shop-cli"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/shopdevs/multi-shop-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shopdevs%2Fmulti-shop-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shopdevs%2Fmulti-shop-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shopdevs%2Fmulti-shop-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shopdevs%2Fmulti-shop-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shopdevs","download_url":"https://codeload.github.com/shopdevs/multi-shop-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shopdevs%2Fmulti-shop-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32433093,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T13:34:34.882Z","status":"ssl_error","status_checked_at":"2026-04-29T13:34:29.830Z","response_time":110,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","cli-tool","developer-tools","devops","multi-shop","nodejs","shopify","shopify-theme-development","shopify-themes-maintenance","theme-development","typescript"],"created_at":"2026-04-29T16:10:14.483Z","updated_at":"2026-04-29T16:10:17.299Z","avatar_url":"https://github.com/shopdevs.png","language":"TypeScript","readme":"# 🚀 Multi-Shop-CLI\n\n[![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)\n[![npm version](https://img.shields.io/npm/v/@shopdevs/multi-shop-cli)](https://www.npmjs.com/package/@shopdevs/multi-shop-cli)\n[![npm downloads](https://img.shields.io/npm/dm/@shopdevs/multi-shop-cli)](https://www.npmjs.com/package/@shopdevs/multi-shop-cli)\n[![codecov](https://codecov.io/gh/shopdevs/multi-shop-cli/branch/main/graph/badge.svg)](https://codecov.io/gh/shopdevs/multi-shop-cli)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n\u003e Contextual development and automated shop management for multi-shop Shopify\n\u003e themes\n\n## What is Multi-Shop-CLI?\n\nTransform any Shopify theme into a sophisticated multi-shop system with\n**contextual development** that adapts to your branch context and **automated\nshop syncing** that keeps all your stores in sync safely.\n\n**Perfect for teams managing multiple Shopify stores** with Dawn theme, custom\nthemes, or any existing Shopify theme that needs multi-shop capabilities.\n\n### ✨ Key Features\n\n- **🧠 Contextual Development** - One command (`pnpm run dev`) adapts to your\n  branch context\n- **🤖 Automated Shop Syncing** - PRs auto-created when main updates\n- **🔐 Secure Credentials** - Developer-specific tokens stored locally only\n- **🎨 Shop Isolation** - Complete separation between shop customizations\n- **⚡ Modern GitHub Flow** - Simple, PR-based development workflow\n- **🧪 Interactive Testing** - Test against real Shopify preview themes\n\n### 🛡️ Built-In Safeguards\n\n- **🚨 Content Protection** (v2.3.0+) - Config-based prevention of content\n  overwrites with strict/warn/off modes\n- **🏥 Health Check** (v2.3.0+) - Comprehensive diagnostics for configuration,\n  credentials, and branches\n- **🎯 Campaign Tools** (v2.3.0+) - Automated campaign lifecycle management with\n  one-command promo workflows\n- **🔒 Security Audit** - `multi-shop audit` command checks permissions and\n  credentials\n- **✅ Tests** - Unit, integration, security, E2E, and performance tests\n- **🌐 Cross-Platform** - Works on Windows, macOS, Linux (Node 18, 20, 22)\n- **📚 Complete Docs** - API reference, guides, and working examples\n\n---\n\n## 🏁 Quick Start\n\n### Installation\n\n```bash\n# Add to your theme project and initialize immediately\ncd your-shopify-theme\npnpm add -D @shopdevs/multi-shop-cli \u0026\u0026 npx multi-shop init\n```\n\nThis creates:\n\n- `shops/` directory for shop configurations\n- GitHub workflow for automated shop syncing\n- Updated package.json with multi-shop-cli scripts\n- Secure credential storage setup\n\n### Set Up Your Shops\n\n```bash\n# Create all your shops interactively\npnpm run shop\n# → Create New Shop\n\n# For each shop, you'll configure:\n# 1. Shop ID (e.g., fitness-store)\n# 2. Display name (e.g., \"Fitness Store\")\n# 3. Production domain (e.g., fitness-store.myshopify.com)\n# 4. Staging domain (e.g., staging-fitness-store.myshopify.com)\n# 5. Authentication method (theme-access-app recommended)\n\n# Repeat for all shops:\n# → shop-a (Shop A)\n# → shop-b (Shop B)\n# → shop-c (Shop C)\n# → shop-d (Shop D)\n```\n\n### Start Development\n\n```bash\n# Use pnpm scripts (recommended)\npnpm run dev\n# → Contextual development that adapts to your branch\n\n# Or use npx directly\nnpx multi-shop dev\n```\n\n---\n\n## 🚀 Complete Setup for Multiple Shops\n\nHere's the step-by-step process to set up multi-shop-cli on a new Shopify theme\n(example shows 4 shops, but you can use any number):\n\n### Step 1: Initialize Project\n\n```bash\ncd your-shopify-theme\npnpm add -D @shopdevs/multi-shop-cli \u0026\u0026 npx multi-shop init\n```\n\n### Step 2: Create All 4 Shop Configurations\n\n```bash\npnpm run shop\n# → Create New Shop\n\n# Shop A\n# Shop ID: shop-a\n# Name: Shop A\n# Production: shop-a.myshopify.com\n# Staging: staging-shop-a.myshopify.com\n# Auth: theme-access-app\n\n# Shop B\n# Shop ID: shop-b\n# Name: Shop B\n# Production: shop-b.myshopify.com\n# Staging: staging-shop-b.myshopify.com\n# Auth: theme-access-app\n\n# Shop C\n# Shop ID: shop-c\n# Name: Shop C\n# Production: shop-c.myshopify.com\n# Staging: staging-shop-c.myshopify.com\n# Auth: theme-access-app\n\n# Shop D\n# Shop ID: shop-d\n# Name: Shop D\n# Production: shop-d.myshopify.com\n# Staging: staging-shop-d.myshopify.com\n# Auth: theme-access-app\n```\n\n### Step 3: Set Up Credentials (Each Developer)\n\nEach developer needs to set up their own theme access tokens:\n\n```bash\n# Create credential files manually:\nshops/credentials/shop-a.credentials.json\nshops/credentials/shop-b.credentials.json\nshops/credentials/shop-c.credentials.json\nshops/credentials/shop-d.credentials.json\n```\n\nExample credential file format:\n\n```json\n// shops/credentials/shop-a.credentials.json\n{\n  \"developer\": \"your-name\",\n  \"shopify\": {\n    \"stores\": {\n      \"production\": { \"themeToken\": \"your-shop-a-production-password\" },\n      \"staging\": { \"themeToken\": \"your-shop-a-staging-password\" }\n    }\n  },\n  \"notes\": \"Theme access app credentials for shop-a\"\n}\n```\n\n### Step 4: GitHub Branches (Automated!)\n\nWhen creating each shop, you'll be prompted:\n\n```bash\n# During shop creation:\n# \"Create GitHub branches for this shop?\"\n# → Yes, create branches automatically (Recommended)\n\n# This automatically creates:\n# shop-a/main and shop-a/staging\n# shop-b/main and shop-b/staging\n# shop-c/main and shop-c/staging\n# shop-d/main and shop-d/staging\n\n# If you chose \"No\" during setup, create manually:\ngit checkout -b shop-a/main \u0026\u0026 git push -u origin shop-a/main\ngit checkout -b shop-a/staging \u0026\u0026 git push -u origin shop-a/staging\n# Repeat for other shops...\n```\n\n### Step 5: Connect Branches to Shopify Themes\n\nFor each shop, connect the Git branches to Shopify themes:\n\n1. **Shopify Admin** → your-shop.myshopify.com → Online Store → Themes\n2. **Add theme** → Connect from GitHub\n3. **Select branch**: `shop-a/main` (for production) or `shop-a/staging`\n4. **Repeat for all shops** (branches already created automatically!)\n\n### Step 6: Verify Setup\n\n```bash\n# Check all shops are configured\npnpm run shop → List Shops\n# Should show your configured shops (e.g., shop-a, shop-b, shop-c, shop-d)\n\n# Check branches exist\ngit branch -r\n# Should show: origin/shop-a/main, origin/shop-a/staging, etc.\n\n# Check credential files exist (each developer)\nls shops/credentials/\n# Should show your shop credential files (e.g., shop-a.credentials.json, shop-b.credentials.json)\n```\n\n### Step 7: Start Developing!\n\n```bash\n# Test contextual development\ngit checkout -b feature/new-header\npnpm run dev\n# → Select shop for testing: shop-a, shop-b, shop-c, or shop-d\n# → Select environment: staging (recommended) or production\n# → Shopify CLI starts with selected shop's credentials\n\n# Test different shops with same code\npnpm run dev  # Try different shop contexts\n# Same feature code, different shop contexts!\n```\n\n---\n\n## 🛠️ How It Works\n\n### Contextual Development\n\nThe system detects your branch context and adapts automatically:\n\n**Feature Branches** (like `feature/new-carousel`):\n\n```bash\npnpm run dev\n# → Prompts for shop context\n# → Prompts for environment (staging/production)\n# → Your code stays on feature branch\n# → Testing happens against selected shop\n```\n\n**Shop Branches** (like `shop-a/custom-checkout`):\n\n```bash\npnpm run dev\n# → Auto-detects \"shop-a\"\n# → Skips shop selection\n# → Starts development immediately\n```\n\n### Automated Shop Syncing (GitHub Flow)\n\nWhen you merge features to main:\n\n1. **Use Tools → Sync Shops**: Select shops and create PRs\n   `main → shop-*/staging`\n2. **Each shop team reviews** their shop-specific PRs\n3. **Shop teams create final PRs**: `shop-a/staging → shop-a/main`,\n   `shop-b/staging → shop-b/main`, etc.\n\n### Campaign Management (Per Shop) - v2.3.0+\n\n**New Campaign Tools Menu** automates the entire campaign lifecycle:\n\n```bash\n# 1. Create promo branch (one command)\npnpm run shop → Campaign Tools → Create Promo Branch\n# → Select shop: shop-a\n# → Promo name: summer-sale\n# → Automatically creates and pushes: shop-a/promo-summer-sale\n\n# 2. Connect promo theme in Shopify admin\n# → Add theme → Connect from GitHub → shop-a/promo-summer-sale\n\n# 3. Customize in Shopify Theme Editor\n# → Changes auto-sync back to promo branch\n\n# 4. Launch promo\n# → Publish theme or use Launchpad app\n\n# 5. Push content back to main (one command)\npnpm run shop → Campaign Tools → Push Promo to Main\n# → Select promo: shop-a/promo-summer-sale\n# → Creates PR: shop-a/promo-summer-sale → shop-a/main\n\n# 6. List all active campaigns\npnpm run shop → Campaign Tools → List Active Promos\n# → Shows all promo branches across all shops\n\n# 7. Clean up after campaign\npnpm run shop → Campaign Tools → End Promo\n# → Select and delete finished promo branch\n```\n\n**Content Protection Integration:** Campaign content merges respect your Content\nProtection settings, ensuring intentional content changes.\n\n### Content Protection (v2.3.0+)\n\n**Config-based safeguards** prevent accidental content overwrites:\n\n```bash\n# View protection status\npnpm run shop → Tools → Content Protection → Show Protection Status\n\n# Configure individual shop\npnpm run shop → Tools → Content Protection → Configure Shop Protection\n# → Select shop\n# → Enable/Disable\n# → Choose mode: strict (block), warn (confirm), or off\n# → Choose verbosity: verbose or quiet\n\n# Enable protection for all shops\npnpm run shop → Tools → Content Protection → Enable All Shops\n\n# Configure global defaults\npnpm run shop → Tools → Content Protection → Global Settings\n```\n\n**Three Protection Modes:**\n\n- **Strict** - Blocks cross-shop content syncs, requires 'OVERRIDE' to proceed\n- **Warn** - Shows warning with file list, requires confirmation (default)\n- **Off** - No protection, content syncs freely\n\n**Smart Detection:** Distinguishes between risky cross-shop operations\n(`main → shop-a`) and safe within-shop operations\n(`shop-a/main → shop-a/staging`).\n\n### Health Check (v2.3.0+)\n\n**Diagnostic tool** verifies your shop configuration:\n\n```bash\n# Check single shop (detailed)\npnpm run shop → Tools → Health Check → Check Single Shop\n# → Verifies: configuration, credentials, branches, content protection\n\n# Check all shops (quick overview)\npnpm run shop → Tools → Health Check → Check All Shops\n# → Shows status for every configured shop\n```\n\n**What it checks:**\n\n- Configuration file validity (JSON, required fields, domains)\n- Credentials existence, tokens presence, file permissions\n- Git branch existence and sync status\n- Content Protection status and settings\n\n**Actionable recommendations** without auto-fixing - tells you exactly what\ncommands to run.\n\n---\n\n## 📋 Development Workflow\n\n### Core Feature Development (GitHub Flow)\n\n```bash\n# 1. Create feature from main\ngit checkout main \u0026\u0026 git checkout -b feature/new-component\n\n# 2. Contextual development\npnpm run dev  # Select shop context for testing\n\n# 3. Test across shops\npnpm run dev  # Try different shop contexts\n\n# 4. Sync with latest main (if needed)\npnpm run sync-main\n\n# 5. Create PR directly to main (GitHub Flow)\ngh pr create --base main --title \"Add new component\"\n\n# 6. After merge → Auto-created shop sync PRs\n```\n\n### Shop-Specific Development\n\n```bash\n# 1. Create shop branch\ngit checkout shop-a/main\ngit checkout -b shop-a/custom-feature\n\n# 2. Auto-detected development\npnpm run dev  # Auto-detects shop-a context\n\n# 3. Create shop PR\ngh pr create --base shop-a/main --title \"Custom feature for Shop A\"\n```\n\n---\n\n## 🏗️ Architecture\n\n### Branch Strategy\n\n```\nmain (core theme)\n├── feature/carousel-fix         # Contextual development\n├── hotfix/critical-bug          # Emergency fixes\n│\n├── shop-a/main                  # Connected to shop-a\n│   ├── shop-a/staging           # Connected to staging-shop-a\n│   └── shop-a/promo-summer      # Campaign branches\n│\n├── shop-b/main                  # Connected to shop-b\n│   ├── shop-b/staging           # Connected to staging-shop-b\n│   └── shop-b/promo-holiday     # Campaign branches\n│\n├── shop-c/main                  # Connected to shop-c\n│   └── shop-c/staging           # Connected to staging-shop-c\n│\n└── shop-d/main                  # Connected to shop-d\n    └── shop-d/staging           # Connected to staging-shop-d\n```\n\n### Security Model\n\n**Shop Configuration** (committed):\n\n```json\n// shops/shop-a.config.json\n{\n  \"shopId\": \"shop-a\",\n  \"name\": \"Shop A\",\n  \"shopify\": {\n    \"stores\": {\n      \"production\": {\n        \"domain\": \"shop-a.myshopify.com\",\n        \"branch\": \"shop-a/main\"\n      },\n      \"staging\": {\n        \"domain\": \"staging-shop-a.myshopify.com\",\n        \"branch\": \"shop-a/staging\"\n      }\n    },\n    \"authentication\": {\n      \"method\": \"theme-access-app\"\n    }\n  }\n  // ⚠️ NO theme tokens stored here\n}\n```\n\n**Developer Credentials** (local only):\n\n```json\n// shops/credentials/shop-a.credentials.json (NOT committed)\n{\n  \"developer\": \"your-name\",\n  \"shopify\": {\n    \"stores\": {\n      \"production\": { \"themeToken\": \"your-personal-production-password\" },\n      \"staging\": { \"themeToken\": \"your-personal-staging-password\" }\n    }\n  },\n  \"notes\": \"Theme access app credentials for shop-a\"\n}\n```\n\n---\n\n## 🧪 Testing\n\n### Interactive Testing with Real Themes\n\n```bash\n# Start dev server\npnpm run dev  # Get preview URL\n\n# Run comprehensive tests\npnpm test:integration     # Shopping flow tests\npnpm test:visual         # Visual regression tests\npnpm test:accessibility  # WCAG compliance tests\npnpm test:performance    # Core Web Vitals tests\n\n# Test shop sync PRs\npnpm run test:pr         # Comprehensive PR testing\n```\n\nAll tests use **real Shopify preview themes** instead of mocks, providing\nrealistic testing conditions.\n\n---\n\n## 🔧 Troubleshooting\n\n### Common Setup Issues\n\n**\"No shops configured yet\"**\n\n```bash\n# Make sure you've created shop configurations:\npnpm run shop → Create New Shop\n# Check: ls shops/ should show *.config.json files\n```\n\n**\"No credentials found for shop-x\"**\n\n```bash\n# Create credential file manually:\n# shops/credentials/shop-x.credentials.json\n# Get theme tokens from Shopify admin or theme access app\n```\n\n**\"Shopify CLI not found\"**\n\n```bash\n# Install Shopify CLI globally:\npnpm add -g @shopify/cli\n\n# Verify installation:\nshopify version\n```\n\n**\"Permission denied\" (Unix/Linux/macOS)**\n\n```bash\n# Fix credential file permissions:\nchmod 600 shops/credentials/*.credentials.json\n```\n\n### Workflow Issues\n\n**\"Can't connect theme to GitHub branch\"**\n\n- Ensure branch exists: `git branch -r | grep shop-a/main`\n- Check Shopify admin → Themes → Add theme → Connect from GitHub\n- Verify repository connection in Shopify\n\n**\"Development server won't start\"**\n\n```bash\n# Check your credentials and domain:\npnpm run shop → List Shops\n# Verify tokens are correct in credential files\n```\n\n**\"Feature branch not detecting context\"**\n\n```bash\n# Check branch name pattern:\ngit branch --show-current\n# Should be: feature/name or shop-a/name for auto-detection\n```\n\n**\"Not sure what's wrong?\" - Run Health Check (v2.3.0+)**\n\n```bash\npnpm run shop → Tools → Health Check\n# Comprehensive diagnostics with actionable recommendations\n# Checks: config, credentials, branches, content protection\n```\n\n---\n\n## 📚 Documentation\n\nComprehensive guides included:\n\n- **Getting Started** - 5-minute setup\n- **Contextual Development** - Core workflow innovation\n- **Shop Management** - Creating and managing shops\n- **Campaign Workflows** - Promo and content management\n- **Testing Guide** - Interactive testing approach\n\n---\n\n## 🤝 Contributing\n\nThis package provides proven multi-shop workflow patterns for any Shopify theme\ndevelopment team.\n\n### Development\n\n```bash\ngit clone https://github.com/shopdevs/multi-shop-cli.git\ncd multi-shop-cli\npnpm install\npnpm test\n```\n\n### Publishing\n\n```bash\nnpm version patch\nnpm publish\n```\n\n---\n\n## 📄 License\n\nMIT © [Brandt Milczewski](https://github.com/brandtam)\n\n---\n\n## 🙏 Acknowledgments\n\n- Built for modern multi-shop Shopify development workflows\n- Inspired by the need for better multi-shop Shopify development workflows\n- Powered by [@clack/prompts](https://www.npmjs.com/package/@clack/prompts) for\n  beautiful CLI experiences\n","funding_links":["https://github.com/sponsors/brandtam"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshopdevs%2Fmulti-shop-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshopdevs%2Fmulti-shop-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshopdevs%2Fmulti-shop-cli/lists"}