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 ./path/to/extension

shopware-cli account producer extension info push ./path/to/extension

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 can build extension assets in complete isolation without needing the Shopware codebase. By default it uses Webpack, but you can opt into esbuild (a Go-based bundler) for significantly faster builds by adding this to your extension's .shopware-extension.yml:

# .shopware-extension.yml - enable esbuild for faster builds
build:
  zip:
    assets:
      enable_es_build_for_admin: true
      enable_es_build_for_storefront: true

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

With esbuild enabled, 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 https://your-shop.example.com

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 extension zip command automatically handles file exclusions, while the --release flag adds release-specific preparation:

• Excludes development files, node_modules, and unnecessary directories from the ZIP
• Runs extension prepare to install Composer dependencies and clean up
• Removes app secrets from manifest.xml (critical for Shopware apps)
• Generates changelog for the release

Local validation before upload

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

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

This runs validation checks against your extension:

• 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

CI/CD builds in one command

Traditional Shopware project builds require running multiple commands in sequence: composer install, asset compilation, file cleanup, and cache warming. The CLI consolidates this into a single CI-optimized command:

# Build Shopware project for CI/CD deployment
shopware-cli project ci

# This automatically:
# 1. Installs Composer dependencies
# 2. Builds administration and storefront assets
# 3. Cleans up unnecessary files
# 4. 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 Fixes 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 code fixes with shopware-cli

The CLI includes integrated automatic code fixing 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 fixes, the CLI automatically detects your target Shopware version from composer.json and applies appropriate upgrade rules:

# Fix entire Shopware project
shopware-cli project fix

# Fix a specific extension
shopware-cli extension fix ./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

Pre-authenticated Admin API access

When debugging API issues or scripting admin operations, manually obtaining OAuth tokens is tedious. The CLI provides a pre-authenticated curl interface to the Admin API:

# Query the Admin API without manual authentication
shopware-cli project admin-api GET /api/product

# Create resources via API
shopware-cli project admin-api POST /api/product '{"name": "Test"}'

# Get just the access token for use in other tools
shopware-cli project admin-api --output-token

This handles OAuth token generation automatically, making it ideal for quick API queries during development or scripting batch operations.

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

Project configuration with YAML

The CLI uses a .shopware-project.yml file to manage project-level configuration, including database dump rules, deployment settings, and extension sync:

shopware-cli project config init

This approach makes project configuration version-controllable and consistent across development environments.

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