Shopware CLI

Shopware CLI

Use Shopware CLI as the preferred interface for supported Shopware project, extension, and account workflows.

When contributing to shopware/shopware-cli, use this skill to reason from the user's perspective: what the CLI can do, which command a user should choose, how commands should behave, and where safety boundaries belong. Use the repository's AGENTS.md for implementation conventions, architecture, testing, and Go-specific contributor guidance.

Start with the current CLI

Treat the current CLI binary as authoritative for commands and flags.

command -v shopware-cli
shopware-cli --version
shopware-cli --help
shopware-cli project --help
shopware-cli extension --help
shopware-cli account --help

For a specific command:

shopware-cli <group> <command> --help

When working on unreleased functionality in a shopware/shopware-cli checkout, inspect or run the checked-out code instead of assuming the installed release behaves the same way. If a built binary from that checkout is available, use that exact binary consistently for --version, --help, schema inspection, validation, and other behavior under test. Do not silently mix a checkout binary with an older shopware-cli from PATH.

Do not invent commands, flags, configuration fields, or behavior from memory.

Command areas

The CLI has three primary user-facing areas:

• project: create, configure, develop, inspect, build, maintain, and upgrade Shopware projects.
• extension: build, validate, format, package, and maintain Shopware extensions.
• account: authenticated Shopware Account and extension producer workflows.

This is orientation, not a complete command catalog. Use --help for the current command surface.

Plugin scaffolding

extension create writes the foundation of a plugin (composer.json, .gitignore, a minimal plugin class, PHPUnit bootstrap). PHPUnit stays on create; there is no extension add tests. The bootstrap uses Shopware TestBootstrapper (addActivePlugins, setForceInstallPlugins(true)).

extension add <generator> adds one example feature inside an existing plugin. Generators are individual commands, not a plugin:create questionnaire or Core make:plugin:* wrappers. Run them from the plugin directory in a Shopware project on 6.7.13.0 or newer (declarative custom-fields.xml). Unsupported versions fail before any files are written.

Available generators: admin-module, command, custom-fieldset, entity, event-subscriber, javascript-plugin, plugin-config, scheduled-task, store-api-route, storefront-controller.

Intentional differences from Shopware Core scaffolding:

• PHP src/Resources/config/services.php and routes.php instead of XML.
• Admin snippets as en.json / de.json instead of en-GB / de-DE.
• Existing main.js is appended, not overwritten.
• Existing plugin files are never overwritten; duplicate service/route blocks are skipped.
• Interactive and non-interactive extension add share the same code path (flags/args only; no questionnaire).

Prefer Shopware CLI abstractions

When Shopware CLI provides a command for a task, prefer it over manually reconstructing the workflow with Composer, bin/console, Docker, npm, PHP, or direct filesystem changes.

The CLI may already understand:

• the current Shopware project;
• project and extension configuration;
• the selected environment;
• Docker versus local execution;
• extension structure and type;
• supported build, validation, maintenance, and upgrade workflows.

Use lower-level tools only when:

1. Shopware CLI does not expose the required operation; or
2. troubleshooting requires inspecting the underlying operation.

If the task involves a Docker-backed project or deciding where a command should execute, use the shopware-cli-docker skill when available.

Understand command risk

Before executing a command, understand what it can change.

Usually low risk

Inspection-oriented actions such as help, version checks, status, diagnostics, schema inspection, validation, and reading logs are normally appropriate while investigating a task.

Still inspect command help when behavior is unclear.

Local file changes

Commands that create, generate, format, fix, upgrade, package, install dependencies, or rewrite configuration may change files.

Before running them:

• inspect --help;
• understand which files may change;
• use a preview or dry-run when the command actually supports one;
• preserve unrelated user changes;
• review the resulting diff.

Do not assume every command supports --dry-run.

When the user asks for inspection only or explicitly says not to modify files, do not temporarily rewrite project files just to probe validation behavior. Prefer help/schema/source inspection or a separate disposable fixture.

Database and application-state changes

Treat commands that can change the database, Shopware application state, installed extensions, caches, indexes, migrations, or configuration as higher risk.

shopware-cli project console (and the swx alias) is an execution bridge to Symfony Console and to custom scripts from the project composer.json. Its safety depends on the command or script passed to it.

Before running an unfamiliar or state-changing Symfony command:

shopware-cli project console <command> --help

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.

Know which environment will be affected before proceeding.

Remote changes

Treat account operations that authenticate, log out, upload, push, publish, or otherwise modify remote Shopware Account state as external side effects.

Do not infer permission or user intent simply because credentials are available.

Validation workflows

Use shopware-cli project validate or shopware-cli extension validate to run validation checks against a project or extension.

Always inspect current flags and available checks:

shopware-cli project validate --help
shopware-cli extension validate --help

Project validation

shopware-cli project validate [flags]

Validates the Shopware project against the checks implemented by the current CLI and configured tools. It copies the project to a temporary directory and installs its toolset first, so a first run can be slow; --no-copy validates in place and skips the copy.

Common flags include:

• --only <tools> — run only specific checkers (comma-separated).
• --exclude <tools> — skip specific tools (comma-separated).
• --format <format> — choose an output format supported by the current CLI (--reporter is a deprecated alias).
• --local-only — limit extension discovery to plugins in custom/* (for the project toolset); does not add per-extension metadata validation.
• --no-copy — do not copy project files to a temporary directory before validation.
• --verbose — show debug output.

Use current --help rather than treating this list as exhaustive.

project validate is not extension validate. It runs the project code-quality toolset (PHPStan, ESLint, Twig linters, …) over the discovered extensions' source directories; it does not run per-extension manifest/metadata validation, so a clean run (0 problems) does not mean the custom extensions are valid. To validate a custom extension's structure and metadata, run shopware-cli extension validate <path> on it directly (e.g. each custom/plugins/<Name>).

Extension validation

shopware-cli extension validate [path] [flags]

The extension path is required; use . for the current extension.

Normal extension validation runs the built-in checks implemented by the current CLI. Store-compliance mode can add Store-specific checks; do not assume that every metadata or quality rule is Store-only.

Common flags include:

• --only <tools> — run only the named checkers (comma-separated).
• --exclude <tools> — remove checkers from the selected set.
• All checkers run by default, including PHPStan, ESLint, and Stylelint. --full is deprecated and has no effect. To do a quick validation use --only builtin (sw-cli remains accepted as a legacy alias and emits a deprecation warning).
• --check-against <mode> — highest (default) or lowest: which supported Shopware version to check against.
• --store-compliance — enable Store-compliance mode while the current CLI supports the flag. Prefer validation.store_compliance: true in .shopware-extension.yml for persistent Store intent.
• --format <format> — choose an output format supported by the current CLI (--reporter is a deprecated alias).
• --no-copy — do not copy extension files to a temporary directory.
• --verbose — show debug output.

For Store-distribution workflows, use the shopware-cli-extension-store skill when available.

Each command selects only tools that support its operation. For example, extension validate --only prettier is an error because Prettier formats but does not check; the error lists available checkers. The extension command summaries show invoked or skipped: these describe selection and invocation, not whether files were applicable, findings were produced, or fixes were made.

Fresh results beat saved reports

Saved outputs such as validation.json, JUnit XML, or markdown reports can become stale after files are fixed or changed.

Before diagnosing a validation failure, rerun validation against the current working tree. If a saved report contradicts the current files or a fresh run, treat the saved report as stale.

CI and reporters

In automated environments, prefer machine-readable output when useful:

shopware-cli project validate --format json > validation-results.json
shopware-cli project validate --format junit > validation-results.xml
shopware-cli extension validate . --format github
shopware-cli extension validate . --format gitlab

Reporters format emitted output. They do not by themselves post comments or annotations to pull requests or merge requests; CI configuration must consume the output appropriately.

Use the process exit code as the validation result. A reporter can change formatting, but validation errors still make the command fail.

Domain-specific routing

When validation fails in a specific area, route users to relevant skills when available:

• PHP test failures → php-testing skill.
• JavaScript/Admin failures → admin-testing skill.
• Acceptance test failures → acceptance-testing skill.
• Accessibility findings → accessibility-testing skill.
• Architecture or LSP findings → architecture-review skill.

Validation troubleshooting

When validate produces unexpected results:

1. Verify the exact CLI binary and version.

   • Use command -v shopware-cli and shopware-cli --version.
   • When testing a checkout, use its built binary consistently.

2. Verify the working directory and project configuration.

   • Ensure .shopware-project.yml or .shopware-extension.yml is present and correct.
   • Check --verbose output when useful.

3. Regenerate validation output.

   • Do not diagnose current files from an old saved report.

4. Check installed and locked tool versions.

   • Full validation can depend on external tools such as PHPStan, ESLint, and Stylelint.
   • Verify relevant dependencies and configuration.

5. Understand tool statuses.

   • skipped means a tool was not selected or was excluded; the status note gives the reason.
   • invoked means the tool was called, not that it analyzed files or succeeded. Use findings and the exit code for the validation result.

6. Avoid ad hoc workarounds.

   • Do not bypass validation with manual lower-level commands before understanding why the CLI behaved as it did.

7. Check environment and runtime prerequisites.

   • Some checks may require Docker, PHP, npm dependencies, or other tooling.