Shopware CLI: Complete Developer Workflow Guide

1. Automating Plugin Store Management

Why manual uploads are inefficient

The traditional plugin upload process requires logging into account.shopware.com, navigating through multiple pages, manually uploading ZIP files, filling out forms, and copying change logs. For developers who release updates frequently, this becomes a significant time sink.

Automated uploads via CLI

The CLI eliminates the manual upload process entirely:

# Upload a plugin to the Shopware store
shopware-cli account producer extension upload path/to/plugin.zip

For CI/CD integration, create a dedicated Shopware account user with API credentials. Store these as environment variables to avoid interactive prompts:

# Set environment variables in your CI pipeline
export SHOPWARE_CLI_ACCOUNT_EMAIL="ci-user@yourcompany.com"
export SHOPWARE_CLI_ACCOUNT_PASSWORD="your-token"

# Upload runs non-interactively in CI
shopware-cli account producer extension upload dist/plugin.zip

Managing store pages with YAML configuration

Instead of manually editing plugin descriptions, highlights, and tags through the web interface, the CLI lets you manage everything through a local YAML file:

shopware-cli account producer extension info pull ExtensionName

shopware-cli account producer extension info push ExtensionName

Automated change log generation from Git

Writing change logs manually is tedious and error-prone. The CLI can extract change logs directly from your Git commit history using regex patterns:

feat(SHOP-123): Add product comparison feature
fix(SHOP-456): Resolve cart calculation rounding error

2. Building Extension Assets Faster

The traditional build challenge

Building extension assets traditionally required the full Shopware codebase to resolve imports and dependencies. This made builds slow and tightly coupled to your Shopware version. Note that Shopware 6.7 has moved from Webpack to Vite for core administration builds, but the principles of slow, dependency-heavy builds remain for traditional approaches.

Standalone builds with shopware-cli

The CLI uses esbuild, a Go-based bundler that builds extension assets in complete isolation. Unlike traditional builds, it doesn't need the Shopware codebase at all:

# Build extension assets (both admin and storefront)
shopware-cli extension build ./path/to/extension

# Build only administration assets
shopware-cli extension build ./path/to/extension --admin-only

Build times drop significantly - from minutes to seconds in many cases. One documented example shows build time reduced from 2 minutes to 7 seconds. The performance improvement is particularly noticeable in CI environments where every second counts.

Lightning-fast development with admin watcher

For administration development, the CLI provides a watcher that starts in under a second (compared to much longer initialization times with traditional watchers):

# Start admin watcher with hot reload
shopware-cli extension admin-watch ./path/to/extension

The watcher automatically rebuilds only changed files, giving you near-instant feedback when developing admin components.

Version-independent builds

Because the CLI builds assets standalone without the Shopware codebase, your builds become version-independent. This means:

• Extensions are more stable across multiple Shopware versions (6.5, 6.6, 6.7+)
• You don't need a full Shopware installation just to build extension assets
• CI/CD pipelines become simpler and faster without Shopware source dependencies
• No need for Node.js - only npm if your extension has a package.json with dependencies

3. Creating Perfect Plugin ZIP Files

Why manual ZIP creation fails

Creating a plugin ZIP file manually is error-prone. You might include unnecessary files like node_modules, forget to compile assets, or accidentally include sensitive files like .env. Each of these mistakes causes store validation to fail.

Automated ZIP creation with --release flag

The CLI handles all ZIP requirements automatically:

# Create a production-ready ZIP file
shopware-cli extension zip ./path/to/plugin --release

The --release flag automatically:

• Removes node_modules and vendor directories
• Excludes development files (GitHub actions, tests, etc.)
• Includes pre-compiled administration and storefront assets
• Removes app secrets (for Shopware apps)

Local validation before upload

Avoid failed uploads by validating your plugin locally before submitting to the store:

# Validate plugin ZIP locally
shopware-cli extension zip validate ./path/to/plugin.zip

This runs the same checks the Shopware store performs:

• PHP syntax validation using WebAssembly (no PHP installation required!)
• Snippet file validation
• Description length requirements (minimum 150 characters)
• Required metadata fields

4. Streamlined Project Deployment

From Git clone to running shop in one command

Traditional Shopware project initialization requires running multiple commands in sequence: composer install, database setup, asset compilation, file cleanup, and cache warming. The CLI consolidates all of this:

# Initialize a Shopware project from Git repository
shopware-cli project init

# This automatically:
# 1. Installs Composer dependencies
# 2. Configures database access
# 3. Builds assets (when necessary)
# 4. Cleans up development files
# 5. Warms up Shopware cache

Deployment optimizations

The CLI's project commands automatically optimize deployments:

• Removes unnecessary files, reducing deployment size by approximately 70 megabytes (significant for Docker images)
• Properly warms cache for production performance
• Handles file permissions correctly

Experimental: Deployment Helper

The CLI includes an experimental deployment helper Composer package that standardizes Shopware installations and updates:

• Installs extensions in the correct order based on the plugin dependency graph
• Allows defining one-time tasks in YAML configuration that run exactly once in production (useful for database fixes)

5. Automatic Code Refactoring for Shopware Upgrades

Why upgrading Shopware versions is challenging

When upgrading between Shopware versions, you often need to update deprecated APIs, adjust template syntax, and modernize code patterns. Doing this manually across hundreds or thousands of files is error-prone and time-consuming.

Automated refactoring with shopware-cli

The CLI includes integrated automatic refactoring that modernizes your codebase when upgrading Shopware versions. It uses industry-standard tools:

• Rector for PHP code transformations (updating deprecated methods, type hints, etc.)
• ESLint for JavaScript updates
• Custom rules for Admin Twig template files

How to use it

For project-wide refactoring, the CLI automatically detects your target Shopware version from composer.json and applies appropriate upgrade rules:

# Refactor entire Shopware project
shopware-cli project refactor

# Refactor a specific extension
shopware-cli extension refactor ./path/to/extension

Experimental: AI-powered Twig template upgrades

The CLI includes experimental LLM-powered Twig template migration that uses AI to propose template adjustments between Shopware versions. This is particularly useful for complex template changes that are difficult to automate with regex rules.

6. Other Useful Features

Public tunnels for local development

When developing payment plugins or webhook integrations, you need a publicly accessible URL for testing. The CLI provides this functionality:

# Create a public tunnel to your local Shopware instance
shopware-cli project tunnel

This creates a temporary public URL that forwards requests to your local development environment, perfect for testing payment provider webhooks.

Anonymized database dumps

Create MySQL dumps with anonymized customer data without requiring MySQL installed locally:

# Create an anonymized database dump
shopware-cli project dump --anonymize

Configuration management with YAML

Manage Shopware system configuration, theme configuration, and mail templates using YAML files instead of clicking through the admin:

shopware-cli project config pull

shopware-cli project config push

This approach makes configuration version-controllable and deployable via CI/CD.

Getting Started with shopware-cli

Installation

The CLI is distributed as a single binary with no dependencies. Download from the official GitHub releases:

# macOS (Homebrew)
brew install shopware/tap/shopware-cli

# Linux (download binary)
curl -L https://github.com/shopware/shopware-cli/releases/latest/download/shopware-cli-linux-amd64 -o shopware-cli
chmod +x shopware-cli
sudo mv shopware-cli /usr/local/bin/

# Windows (download from releases page)
# Visit: https://github.com/shopware/shopware-cli/releases

First steps

1. Authenticate with your Shopware account:

   shopware-cli account login

2. Navigate to your plugin directory and try building assets:

   shopware-cli extension build .

3. Create a production ZIP file:

   shopware-cli extension zip . --release