New Development Workflow using Docker + shopware-cli

[lasomethingsomething]

Problem statement

Discussed in shopware/shopware#14993

^{Originally posted by shyim February 16, 2026}

The Problem

Setting up a Shopware development environment is not straightforward; they are many options to use.
- we've downgraded a few, but users may still hold onto them out of familiarity or concerns about containerization.
All setups have their drawbacks and which option the developer chooses defines a totally different experience. Also many variations lead to fragmentation, which makes it difficult to optimize the software for a specific stack and confuses new developers.

The Solution

A single CLI that handles everything: from bootstrapping a new project to managing multiple deployment environments. Why: No manual setup, no configuration drift, no context switching between tools.

(This can be the command for the CLI/Builders landing page block; will also need to be included in CLI devdocs)

[!NOTE]
The user does not need to install the CLI, it can be run also directly using npx @shopware-ag/shopware-cli <command>

shopware-cli project create my-shop
cd my-shop
shopware-cli project dev

That's it. You're able to develop.

Quick Start (Implemented)

1. Create a Project

shopware-cli project create my-shop

This command (all implemented):

• Lets you pick a Shopware version interactively (all stable releases from 6.4.18+)
• Installs everything via Docker (no local PHP required)
• Creates a .shopware-project.yml with a Docker environment pre-configured (this says the local setup is Docker)
• Pre-configured CI/CD workflows for GitHub Actions / Gitlab CI
• Optional: Deployment pre-configured using Deployer PHP

2. Start Developing (WIP); replacement for the make file. instead of make up you'd run this instead)

shopware-cli project dev

This opens an interactive TUI with tabs. User stories, in order/flow:

• 1. Start installation from the TUI: As a developer, I want to start Shopware installation from an interactive terminal UI, so that I can set up my project without manually entering all options via CLI flags.
• 2. Choose whether to install Shopware: As a developer, I want the TUI to ask whether I want to install Shopware, skip installation, or quit, so that I can control the setup flow from the first screen.
• 3. Select the default installation language: As a developer, I want to choose the default language to install from the same options as the language pack/First Run Wizard, so that the shop is initialized in the language I need.
• 4. Select the default currency: As a developer, I want to choose the default currency for the shop during setup, so that the initial shop configuration matches my target market.
• 5. Enter admin credentials during installation: As a developer, I want the installer to enable me to enter the admin username and password, so that I can access the Administration immediately after setup.
• 6. Toggle password visibility: As a developer, I want a password eye-toggle in the TUI, so that I can temporarily reveal the password while typing and avoid input mistakes.
• 7. See a live summary of chosen values: As a developer, I want the question panel to show my currently selected answers as I progress through setup, so that I can review my choices before submitting the installation.
• 8. Confirm installation with Enter: As a developer, I want to confirm my setup choices by pressing Enter, so that the installation starts with a familiar terminal interaction/one-click.

Installation progress and deployment helper

• 9. View installation progress in a deployment helper screen: As a developer, I want to see a deployment helper view after confirming the setup, so that I can follow the progress of the Shopware installation.
• 10. See installation logs while the shop is being installed: As a developer, I want the deployment helper to display installation logs, so that I can understand what is happening during setup and diagnose failures.
• 11. Replace or hide verbose logs with a simpler default progress view: As a developer, I want the installation view to optionally hide the verbose deployment helper logs (behind Arnold's component?) and show a progress bar by default, so that the setup experience feels cleaner and less overwhelming.

Post-install dashboard

• 12. Land on a dashboard after installation: As a developer, I want to be taken to a dashboard after installation finishes, so that I immediately see how to access and use my local Shopware instance.
• 13. See core instance information on the dashboard: As a developer, I want the dashboard to show basic instance information such as environment, shop URL, and admin URL, so that I can quickly access my running project.
• 14. Access keyboard shortcuts from the dashboard: As a developer, I want the dashboard to tell me that I can press F for shortcuts, so that I can discover and use keyboard-driven interactions more efficiently.
• 15. See available services on the dashboard: As a developer, I want the dashboard to show the services available in my local setup, so that I know which supporting tools are running and avoid extra manual setup. (Adminer/enables you to look at the database tables; queue (its own tool) so you can look at background events/processes happening; mailpit/inspect outgoing emails generated by the shop)
• 16. See admin access information on the dashboard: As a developer, I want the dashboard to show admin access information, so that I can quickly log into the Administration after setup.
• 17. Auto-discover services from Docker Compose ports: As a developer, I want services to be auto-discovered from Docker Compose port definitions, so that the dashboard can list available tools without requiring manual configuration.

Logs experience

• 21. Switch between the dashboard view and logs: As a developer, I want to switch between the general dashboard view and a logs view, so that I can move quickly between system information and debugging output.

• 22. Read Shopware log output in the logs tab: As a developer, I want the logs tab to show Shopware logs, including the default dev.log, so that I can diagnose application behavior from within the terminal UI.

• 23. Read Docker logs in the logs tab: As a developer, I want the logs tab to include Docker logs, so that I can debug container-level issues without leaving the terminal UI.

• 24. Read database logs in the logs tab: As a developer, I want the logs tab to include database logs, so that I can identify persistence and query-related issues from the same interface.

• 25. Stream logs in real time: As a developer, I want the logs tab to stream container logs in real time directly into the terminal, so that I can observe live activity while working locally.

• 26. Distinguish logs by source: As a developer, I want logs to be labeled by source, such as app, db, and worker, so that I can quickly understand where a message is coming from.

• Dependency: Hide Shopware-owned deprecations in the logs view: As a developer building extensions, I want the logs view to suppress deprecations originating from Shopware itself, so that I can focus on issues that affect my own build and extension development. (dependency: needs to be addressed in the Core itself; not a Q2 goal. Quality issue, to take up with A and Paul. Doesn't impact CLI directly, but does impact overall user experience. When there are new deprecations every day, you stop caring/get worn out. Too many. When you install the software you should have zero deprecations when you install new software, and your log file is empty. Why are users outdated when you just started?)

Exit and lifecycle handling

• 27. Exit the TUI with keyboard shortcuts: As a developer, I want to be able to leave the TUI by pressing Ctrl+C or Q, so that I can exit the interface using common terminal controls.
• 28. Decide whether containers should keep running on exit: As a developer, I want the TUI to ask whether Docker containers should be stopped or kept running when I exit, so that I can control resource usage and preserve my local environment when needed.
• 29. Return to the CLI access view after quitting: As a developer, I want quitting the TUI to return me to the CLI “access your shop” view, so that I do not lose context after leaving the interactive interface.

Environment: local (docker)

Shopware Administration: http://localhost:8000/admin
  Username: admin
  Password: shopware

Services:
  Mail-Catcher: http://localhost:8025
  Queue Dashboard: http://localhost:15672
    Login: guest / guest

Customization tab (to do)

• 30. Open a customization tab: As a developer, I want a dedicated Customization tab in the terminal UI, so that I can manage development-related project settings in one place.
• 31. Configure debugger support: As a developer, I want a debugger option in the Customization tab, so that I can enable or manage debugging behavior for local development.
• 32. Choose the PHP version: As a developer, I want to choose which PHP version the project should use, so that I can align my local environment with project requirements.
• 33. Inspect profiling information: As a developer, I want a profiling option that helps me understand what is slow on a page, so that I can investigate performance bottlenecks during development.
• 34. [P1] Configure local environment settings: As a developer, I want a local environment settings area in the Customization tab, so that I can configure project-specific development settings from the terminal UI.
• 35. [P2] Persist local development settings: As a developer, I want a foundation for storing local project settings, so that each developer can keep and change their own Shopware project configuration locally.
• 36. [P0] Surface configuration mistakes: As a developer, I want the tool to identify configuration mistakes, so that I can correct local setup problems before they cause failures.
• 37. [P1] Suggest better-performing configuration: As a developer, I want the tool to suggest improved local configuration for better performance, so that I can optimize my environment without manually researching best practices.

Logs tab already exists - real-time container logs, streamed directly into the terminal:

[app]    2026-02-16 10:00:01 [info] Matched route "frontend.home.page"
[db]     2026-02-16 10:00:01 [Note] MariaDB ready for connections
[worker] 2026-02-16 10:00:02 [info] Message handled successfully

Services are auto-discovered from Docker Compose ports.

Extensions tab

See #1063

• 38. [P0] Manage extensions from the terminal UI: As a developer, I want a future Extensions tab in the terminal UI, so that I can manage plugins without leaving the terminal.
• 39. [P0] Upgrade Shopware from the terminal UI: As a developer, I want to choose which Shopware version to upgrade to from the terminal UI, so that I can manage upgrades from the same interface I use for local development.
• 40. [P0] Run extension compatibility checks before upgrading: As a developer, I want to check extension compatibility against a target Shopware version before upgrading, so that I can identify upgrade risks in advance.
• 41. [P0] Review compatibility results per extension: As a developer, I want to see compatibility results in rows for each extension, so that I can evaluate which extensions are ready for the upgrade.
• 42. [P0] Choose whether to proceed with upgrade after compatibility checks: As a developer, I want the terminal UI to let me decide whether to continue with an upgrade after seeing compatibility results, so that I stay in control of risky version changes.

Shopware Account integration (high-effort, includes SBP; more a Q4 issues, add GH issue pointing to Jira issue)

Business questions:

• Do we want every dev to have an account?
• How integrated should it be?
• Benefits to users: in-terminal/avoids tabbing back and forth, and you can install free extensions without all the back and forth (currently set up domain, verify, first time may take one hour to do it so this lowers TCO)
• 43. [P1] Link the local shop to a Shopware Account from the CLI: As a developer, I want to link my local shop to my Shopware Account directly from the CLI, so that account-connected workflows are available without switching tools.
• 44. [P1] Suggest extensions from the Shopware Account in the CLI: As a developer, I want the CLI to suggest free and paid extensions from my Shopware Account, so that I can discover relevant add-ons directly in my local workflow.
• 45. [P1] Install account-linked extensions from the CLI: As a developer, I want to install free and paid extensions from my Shopware Account directly from the CLI, so that I can extend my local shop without leaving the terminal.

3. Build and Watch Assets

These commands are already in the CLI and functional.

• Integrated them into the TUI, to show whether admin-build is running, and when it's failing, show the logs.
• Integrated for storefront into the TUI.
• User can also see where the watcher is running, toggle it on/off.

# Build for production
shopware-cli project admin-build
shopware-cli project storefront-build

# Watch mode for development (hot reload)
shopware-cli project admin-watch
shopware-cli project storefront-watch

4. Run Console Commands

• [WIP] Proxy the core CLI via the Shopware CLI to remove one layer of CLI, and so that you have your regular shell. (Addresses complaint about Docker setup, that you lose your shell.)
• [WIP] get full list of bin/console commands TODO) and streamline existing Shopware CLI commands (esp around accounts section)
• Execute any of the 120 bin/console commands in shopware/shopware without entering the container:

shopware-cli project console cache:clear
shopware-cli project console plugin:create MyPlugin
shopware-cli project console plugin:install MyPlugin --activate

• We could ship also an alias for faster typing (could ask users if this is helpful, also what the alias actually is)

swx cache:clear
swx plugin:create Fooo

Full shell completion is included - plugin names, command names, and arguments are auto-completed.

Multi-Environment Management

This is where the CLI truly shines. Define all your environments in one file and operate on any of them with a single flag.

Questions and risks to resolve:

• How deep do we want to go? Upgrade command, should it be possible across hosting models?
• For SSH: when upgrading, do we run Deployer?
• Start with local Docker, Symfony options in iteration 1; then think about how it integrates with remote things (SSH, PaaS, SaaS shops)
• Permissions: going incrementally, starting with the local Docker and Symfony options, will surface concerns and how to address

Add Environments via TUI

shopware-cli project config manage

An interactive form guides you through adding any environment type - SSH credentials, Docker settings, PaaS configuration - without editing YAML by hand.

Supported Environment Types

Type	Use Case	How It Works
docker	Local development	Executes via docker compose exec, auto-discovers services from ports
local	Native PHP setup	Direct PHP/Composer execution, reads DATABASE_URL from .env
symfony-cli	Symfony server users	Wraps symfony console, symfony composer, symfony php
ssh	Traditional hosting	Remote execution via SSH with connection pooling and key auth
paas	Platform.sh / Shopware PaaS	SSH-based execution with provider-aware configuration

One Flag, Any Environment

Every project command works across all environment types with the -e flag:

# Clear cache on staging
shopware-cli project -e staging console cache:clear

The default environment is local. If no environments are configured, Docker is auto-detected from existing compose files.

Example Configuration

environments:
  local:
    type: docker
    url: http://localhost:8000
    admin_api:
      username: admin
      password: shopware

  staging:
    type: ssh
    url: https://staging.example.com
    connect_options:
      host: staging.example.com
      username: deploy
      private_key: ~/.ssh/id_rsa
      project_dir: /var/www/shopware
    admin_api:
      username: admin
      password: ${STAGING_ADMIN_PASSWORD}

  production:
    type: ssh
    url: https://www.example.com
    connect_options:
      host: prod.example.com
      username: deploy
      private_key: ~/.ssh/id_rsa
      project_dir: /var/www/shopware

Secrets can reference environment variables (${VAR}) to keep credentials out of version control.

Database Synchronization

Sync data between environments with built-in GDPR-compliant anonymization.

Export a Database Dump

# Dump with compression
shopware-cli project dump --output backup.sql.gz

# Dump from staging
shopware-cli project -e staging dump --output staging.sql.zst

# Clean dump (excludes carts, logs, messenger queue)
shopware-cli project dump --clean

# Anonymize customer data for GDPR compliance
shopware-cli project dump --anonymize

Import a Dump

# Auto-detects compression format (.gz, .zst, or plain SQL)
shopware-cli project import staging.sql.zst

Typical Workflow: Refresh Local from Production

# 1. Create an anonymized dump of production
shopware-cli project -e production dump --anonymize --clean --output prod.sql.zst

# 2. Import into local environment
shopware-cli project import prod.sql.zst

Integration into Deployment Helper

The Deployment Helper uses already the same configuration file as shopware-cli. So it will be also aware of environments, that you can:

environments:
  staging:
    deployment:
       extension-management:
          overrides:
            GoogleAnalytics:
              state: remove

so when you deploy to staging, that the Analytics plugin will be removed if it was installed.

Command Reference

Command	Description
project create	Bootstrap a new Shopware project
project dev	Start the interactive TUI (services + logs)
project console <cmd>	Execute bin/console commands
project admin-build	Build Administration assets
project admin-watch	Watch Administration assets (hot reload)
project storefront-build	Build Storefront assets
project storefront-watch	Watch Storefront assets (hot reload)
project dump	Export a database dump
project import db <file>	Import a database dump
project config manage	Manage environments via TUI
project validate	Run code quality checks
project format	Run code formatters

Further ideas

Import / Export entire Shops

Right now shopware-cli allows to export a database dump, we could also think about exporting an entire shop: dump + all assets.
In that way you could export a production shop, import it locally to have the same database + all uploaded assets.

There are several use-cases:

• Replicate a existing installation
• Move between hosting options as a unified way.
• Unified Backup strategy of a Shop

Business / user impact

See above

Proposed solution

No response

Who benefits?

No response

Out of scope

No response

Acceptance criteria

TBD

Readiness checklist

• Acceptance criteria are clearly defined.
• Backward compatibility impact addressed.
• Developer docs written.
• Tests added or adjusted accordingly.

[lasomethingsomething]

Missing things for first deliverable of devtui (moves content from #1001):

• Project Create chooses the highest possible PHP version OOB
• When running devtui in a non docker environment, allow to migrate to it

[shyim]

Testing

Platform: Linux/macOS/Windows (WSL2)

New Project

• Create Project using CLI
• Start Project using TUI (shopware-cli project dev)
• Install using TUI (you get asked)
• Check if log tab is updating
• Start / Stop admin and storefront watcher using (STRG+P command plate)
• Stop environment

Non interactive way

• Start with shopware-cli project dev start
• Shopware runs at http://127.0.0.1:8000
• Start admin watcher using shopware-cli project admin-watch

Migrate existing project

• Create project old way, go to empty dir: docker run --rm -it -v $PWD:/var/www/html ghcr.io/shopware/docker-dev:php8.3-node24-caddy new-shopware-setup
• Launch Tui for Migration Wizard: (shopware-cli project dev)
• Everything should work as it is

[ravenokko]

The initial UX could use a little polish. Currently, there's swapping back and forth from tabs and docker when you first start project dev

swcli.mov

[ravenokko]

If you use the Clear Cache command there's no feedback anything is happening

Similarly with Build Storefront/Admin, some places (i.e. when it's installing npm dependencies) you can't be sure if anything is happening or if it crashed/is stuck in an infinite loop.

[shyim]

If you use the Clear Cache command there's no feedback anything is happening

fixed with #1068

Similarly with Build Storefront/Admin, some places (i.e. when it's installing npm dependencies) you can't be sure if anything is happening or if it crashed/is stuck in an infinite loop.

will be fixed with #1069

[gweiermann]

Currently, I'm running two Shopware instances in parallel.

It would be helpful if there were support for automatically using a different port when the default one is already in use (suggestion from SCDs audience).

I also really like OrbStack's domain resolution approach. Being able to access instances via dedicated subdomains such as admin.instance1.shopware.local and admin.instance2.shopware.local would significantly improve my developer experience and make it easier to work with multiple instances simultaneously.

[lasomethingsomething]

Thanks for the input, Gerrit Weiermann (@gweiermann) -- I created a separate user story for your comment: #1094

We also have #939 in our backlog, which partially overlaps.