Shopware CLI Docker

Shopware CLI with Docker

In a Shopware CLI-managed Docker project, prefer asking Shopware CLI to perform the operation instead of manually deciding how to enter containers.

Shopware CLI knows the project configuration and selected execution environment and can route supported operations through the correct executor.

Core rule

Do not default to:

docker compose exec ...

when Shopware CLI already exposes the operation.

Prefer:

shopware-cli project ...

The CLI should decide when Docker is required.

Symfony and Shopware Console commands

When a task requires bin/console, use:

shopware-cli project console <command> [arguments]

Instead of manually doing something like:

docker compose exec web php bin/console <command>

prefer:

shopware-cli project console <command>

project console resolves the current Shopware project and its configured executor. In a Docker-backed environment, the CLI routes the Symfony command or Composer script through the project container.

For the full Composer CLI, use:

shopware-cli project composer <arguments>

Instead of manually doing something like:

docker compose exec web composer <arguments>

In a Docker-backed environment, the CLI routes the Composer command through the project container.

This applies to Shopware and Symfony Console workflows such as:

• cache commands;
• plugin and app lifecycle;
• indexing;
• migrations;
• scheduled tasks;
• system configuration;
• other commands exposed by bin/console;
• custom Composer scripts from the project composer.json.

Before executing an unfamiliar or state-changing Symfony command:

shopware-cli project console <command> --help

Do not assume a Symfony command is safe merely because it exists.

Discover Composer scripts from the project composer.json or shopware-cli project console list. Do not pass --help to a Composer script to inspect it; that argument is forwarded to the script and can still run it.

Development environment

Use Shopware CLI to manage the development environment:

shopware-cli project dev
shopware-cli project dev start
shopware-cli project dev status
shopware-cli project dev stop

Do not replace these with docker compose up or docker compose down unless there is a specific reason to bypass the CLI.

The CLI knows the configured environment and can prepare and manage the Docker setup required by the project.

Other project operations

Prefer the corresponding Shopware CLI command for supported tasks such as builds, watchers, logs, validation, upgrades, project maintenance, and extension management.

Do not manually wrap a Shopware CLI command in docker compose exec.

If Shopware CLI already exposes the operation, let the CLI handle Docker.

Database work

First determine what kind of database operation the user actually needs.

For database exports, inspect:

shopware-cli project dump --help

For database-related operations exposed through Symfony or Shopware Console, prefer:

shopware-cli project console <command>

For arbitrary SQL, first inspect the available Shopware CLI and Symfony commands. Do not invent a CLI command.

If no suitable Shopware CLI abstraction exists, direct database access may be necessary. Before doing that:

1. identify the configured database service and target environment;
2. prefer discovered configuration over hard-coded container names or credentials;
3. use read-only queries where possible;
4. treat writes, deletes, schema changes, imports, and bulk updates as destructive operations.

Never execute database-changing commands against an ambiguous environment.

Composer, PHP, and npm

Prefer a higher-level Shopware CLI operation when one exists.

Do not immediately run:

docker compose exec web composer ...
docker compose exec web php ...
docker compose exec web npm ...

First check whether Shopware CLI already exposes the intended workflow.

For Composer itself, prefer:

shopware-cli project composer ...

If no CLI abstraction exists:

1. confirm this using the relevant command group's --help;
2. determine the configured Docker service and working directory;
3. run the low-level tool in the correct project environment;
4. avoid hard-coding paths and service names when they can be discovered.

Direct Docker execution is the fallback, not the default.