diff --git a/.wordlist.txt b/.wordlist.txt index bce4dfa739..a9867f073d 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -889,6 +889,7 @@ Roadmap RouteResponse RuleConditionService RuntimeException +SBOM SBP SCSS SDK diff --git a/products/tools/cli/automatic-refactoring.md b/products/tools/cli/automatic-refactoring.md index 43ed91ae26..e2f508c062 100644 --- a/products/tools/cli/automatic-refactoring.md +++ b/products/tools/cli/automatic-refactoring.md @@ -7,9 +7,15 @@ nav: # Automatic refactoring -Shopware CLI includes a built-in automatic refactoring tool that helps you automatically update and clean up code in your Shopware projects and extensions. +Shopware CLI includes a built-in automatic refactoring tool with pre-configured rules for Shopware projects. Instead of manually configuring and managing multiple linters and fixers, this tool automatically handles breaking changes and code modernization when you upgrade Shopware versions. -Use this tool to modernize your codebase when upgrading to a new Shopware version or to apply best-practice changes automatically. +Use this tool to: + +- Automatically fix breaking changes between Shopware versions +- Apply Shopware-idiomatic code fixes +- Modernize your codebase without manual linter configuration + +The tool uses: - [Rector](https://getrector.com/) for PHP - [ESLint](https://eslint.org/) for JavaScript @@ -79,6 +85,23 @@ The CLI runs Rector and ESLint automatically. After completion, review all chang Make sure the `shopware/core` requirement in your `composer.json` file reflects the version you're targeting. Shopware CLI determines which upgrade rules to apply based on that version constraint. +### Project fix options + +Run only specific tools: + +```shell +shopware-cli project fix /path/to/your/project --only phpstan +shopware-cli project fix /path/to/your/project --only "phpstan,eslint" +``` + +Allow running on non-Git repositories: + +```shell +shopware-cli project fix /path/to/your/project --allow-non-git +``` + +By default, `project fix` requires a Git repository to safely track changes. + ## After running refactoring Use Git or your diff tool to review the changes. diff --git a/products/tools/cli/extension-commands/build.md b/products/tools/cli/extension-commands/build.md index 92b629836e..64a4b816bd 100644 --- a/products/tools/cli/extension-commands/build.md +++ b/products/tools/cli/extension-commands/build.md @@ -44,7 +44,7 @@ build: ## Extension as bundle -If your extension is not a plugin but itself a bundle, make sure your composer type is `shopware-bundle` and that you have set a `shopware-bundle-name` in the `extra` part of the composer definition like this: +If your extension is not a plugin but itself a bundle, make sure your Composer type is `shopware-bundle` and that you have set a `shopware-bundle-name` in the `extra` part of the composer definition like this: ```json { @@ -59,13 +59,13 @@ If your extension is not a plugin but itself a bundle, make sure your composer t Now you can use `shopware-cli extension build ` to build the assets and distribute them together with your bundle. Also `shopware-cli project ci` detects know automatically this bundle and builds the assets for it. -## Using `esbuild` for JavaScript bundling +## Using esbuild for JavaScript bundling ::: warning Building with esbuild works completely standalone without the Shopware codebase. This means if you import files from Shopware, you have to copy it to your extension. ::: -Esbuild can be used for JavaScript bundling, offering a significantly faster alternative to the standard Shopware bundling process, as it eliminates the need to involve Shopware for asset building. +An esbuild bundle can be used for JavaScript bundling, offering a significantly faster alternative to the standard Shopware bundling process, as it eliminates the need to involve Shopware for asset building. ```yaml # .shopware-extension.yml @@ -78,21 +78,31 @@ build: enable_es_build_for_storefront: true ``` +### Content-addressable assets and Vite manifest + +When building with esbuild, Shopware CLI emits content-hashed variants of the +compiled JS and CSS files (e.g. `-.js`) alongside files without hashes in the same directories. + +- **Shopware 6.7+**: The generated `.vite/manifest.json` and `.vite/entrypoints.json` reference the hashed filenames, so browser and CDN caches are invalidated automatically whenever the extension assets change. Note that an existing `.vite/manifest.json` is overwritten on each esbuild build. +- **Shopware < 6.7**: The files without hashes are kept for backward compatibility and continue to be loaded as before. + +No configuration is required. This happens automatically when esbuild is enabled. + ## Creating an archive To create an archive of an extension, you can use the following command: ```bash -shopware-cli extension zip +shopware-cli extension package ``` -The command copies the extension to a temporary directory, builds the assets, deletes unnecessary files and creates a zip archive of the extension. The archive is placed in the current working directory. +The command copies the extension to a temporary directory, builds the assets, deletes unnecessary files and creates a ZIP archive of the extension. The archive is placed in the current working directory. **By default, the command picks the latest released git tag**, use the `--disable-git` flag to disable this behavior and use the current source code. Besides disabling it completely, you can also specify a specific tag or commit using `--git-commit`. -### Bundling composer dependencies +### Bundling Composer dependencies -Before Shopware 6.5, bundling the composer dependencies into the zip file is required. Shopware CLI automatically runs `composer install` and removes duplicate composer dependencies to avoid conflicts. +Before Shopware 6.5, bundling the Composer dependencies into the ZIP file is required. Shopware CLI automatically runs `composer install` and removes duplicate Composer dependencies to avoid conflicts. To disable this behavior, you can adjust the configuration: @@ -106,9 +116,9 @@ build: This is automatically disabled for plugins targeting Shopware 6.5 and above and `executeComposerCommands` should be used instead. -### Delete files before zipping +### Delete files before packaging -Shopware CLI deletes a lot of known files before zipping the extension. If you want to delete more files, you can adjust the configuration: +Shopware CLI deletes a lot of known files before packaging the extension into a ZIP file. If you want to delete more files, you can adjust the configuration: ```yaml # .shopware-extension.yml @@ -136,7 +146,7 @@ This skips unnecessary `npm install` and `npm ci` commands and only installs the ### Checksums -When creating an archive using `shopware-cli extension zip`, a `checksum.json` file is automatically generated. This file contains checksums for all files in the extension, which can be used to verify the integrity of the extension after installation. +When creating an archive using `shopware-cli extension package`, a `checksum.json` file is automatically generated. This file contains checksums for all files in the extension, which can be used to verify the integrity of the extension after installation. If you want to exclude certain files or paths from the checksum calculation, you can configure this in your `.shopware-extension.yml` file: @@ -165,7 +175,18 @@ To verify the checksum of installed extensions, you can use the [FroshTools](htt ### Release mode -If you are building an archive for distribution, you can enable the release mode with the flag `--release`. This will remove the App secret from the `manifest.xml` and generate changelog files if enabled. +When building an extension for distribution to the Shopware Store or installation in a Shopware instance, enable release mode with the `--release` flag: + +```bash +shopware-cli extension package --release +``` + +Release mode: + +- Removes secrets: Strips out sensitive data that may have been committed during development (credentials, API keys, app secrets) +- Generates changelog: Automatically creates changelog files from Git commits (if enabled in configuration) + +This is important when distributing extensions because developers often commit configuration files with secrets during development that shouldn't be included in the final package. The changelog generation can be enabled with the configuration: @@ -196,22 +217,22 @@ With the combination of `pattern`, `variables` and `template` we link the commit ### Overwrites -Extension configuration can be overwritten during the zipping process, allowing changes to aspects such as the version and app-related settings. +Extension configuration can be overwritten during the packaging process, allowing changes to aspects such as the version and app-related settings. Replaces the version in `composer.json` or `manifest.xml` with the given version: ```yaml -shopware-cli extension zip --overwrite-version=1.0.0 +shopware-cli extension package --overwrite-version=1.0.0 ``` Replaces all external URLs in `manifest.xml` to that given URL: ```yaml -shopware-cli extension zip --overwrite-app-backend-url=https://example.com +shopware-cli extension package --overwrite-app-backend-url=https://example.com ``` Replaces the App secret in `manifest.xml` with the given secret: ```yaml -shopware-cli extension zip --overwrite-app-backend-secret=MySecret +shopware-cli extension package --overwrite-app-backend-secret=MySecret ``` diff --git a/products/tools/cli/extension-commands/configuration.md b/products/tools/cli/extension-commands/configuration.md index 030e394823..681a22064a 100644 --- a/products/tools/cli/extension-commands/configuration.md +++ b/products/tools/cli/extension-commands/configuration.md @@ -44,6 +44,10 @@ validation: When you edit that file in an editor, you will get autocompletion and hints for the available options. +::: info +To programmatically access the configuration schema, use `shopware-cli extension config-schema`. This outputs the JSON schema and is particularly useful for AI agents and automation tools that need to understand the extension configuration structure. +::: + ## Compatibility date You can define a `compatibility_date` in `.shopware-extension.yml`: diff --git a/products/tools/cli/extension-commands/extract-meta-data.md b/products/tools/cli/extension-commands/extract-meta-data.md index 5d2f8eaee0..09d78966e4 100644 --- a/products/tools/cli/extension-commands/extract-meta-data.md +++ b/products/tools/cli/extension-commands/extract-meta-data.md @@ -7,7 +7,7 @@ nav: # Extracting Meta Data -There are helpers in Shopware CLI to extract data of an extension. This is useful in your CI/CD pipeline to get the extension version or the changelog for the automated release. +There are helpers in Shopware CLI to extract data of an extension. This is useful in your CI/CD pipeline to get the extension version, name, or the changelog for the automated release. ## Extracting the version @@ -19,6 +19,16 @@ shopware-cli extension get-version The path can be absolute or relative to the current working directory. The command will output the version of the extension. +## Extracting the name + +To extract the name of an extension, you can use the following command: + +```bash +shopware-cli extension get-name +``` + +The path can be absolute or relative to the current working directory. This is useful in CI/CD pipelines when you need to programmatically determine the extension identifier. + ## Extracting the changelog To extract the changelog of an extension, you can use the following command: @@ -30,3 +40,13 @@ shopware-cli extension get-changelog The path can be absolute or relative to the current working directory. The command will output the changelog of the extension. It will output always the English changelog. + +## Configuration schema + +To view the JSON schema for the `.shopware-extension.yml` configuration file, you can use: + +```bash +shopware-cli extension config-schema +``` + +This outputs the JSON schema that describes all available configuration options in `.shopware-extension.yml`. This is particularly useful for AI agents and automation tools that need to understand the extension configuration structure. diff --git a/products/tools/cli/index.md b/products/tools/cli/index.md index 028524a68a..05801da903 100644 --- a/products/tools/cli/index.md +++ b/products/tools/cli/index.md @@ -67,3 +67,9 @@ COPY --from=ghcr.io/shopware/shopware-cli:bin /shopware-cli /usr/local/bin/shopw **Binary & releases:** Prebuilt packages and archives are published at [shopware/shopware-cli · Releases](https://github.com/shopware/shopware-cli/releases). + +## Telemetry + +Shopware CLI collects limited usage telemetry to help us improve the tool and understand which features are most valuable to you. No personal data, credentials, or file contents are collected. You can opt out anytime by setting the `DO_NOT_TRACK` environment variable. + +See [Telemetry & Privacy](../../../resources/references/telemetry.md#shopware-cli) for full details about what data is collected and how to disable telemetry. diff --git a/products/tools/cli/project-commands/autofix.md b/products/tools/cli/project-commands/autofix.md index 4559e7400c..956bf48aea 100644 --- a/products/tools/cli/project-commands/autofix.md +++ b/products/tools/cli/project-commands/autofix.md @@ -11,7 +11,7 @@ Shopware-CLI comes with some builtin auto fixers for project migrations. ## Migrate a project to Symfony Flex -Prior to Shopware 6.5, Shopware didn't use Symfony Flex. This means that the project structure was different, and some configuration files were located in different places. The `shopware-cli project autofix flex` command will migrate your project to Symfony Flex and move all configuration files to the correct locations. +Shopware 6.4 and earlier used a different project structure without Symfony Flex. When upgrading to Shopware 6.5 or later, the `shopware-cli project autofix flex` command will migrate your project from the legacy structure to Symfony Flex, moving all configuration files to the correct locations. ::: warning Ensure that you have a backup of your project before running this command. @@ -25,8 +25,19 @@ The command will delete all unnecessary configuration files. It will also update ## Migrate custom/plugins extensions to Composer -It's best practice to manage the store and your custom plugins via Composer. [If you want to learn more about this check out this guide](../../../../guides/hosting/installation-updates/extension-management.md). Shopware-CLI has a helper for migrating locally installed plugins to Composer through Shopware Packagist for the Shopware Store. Make sure you have a Shopware Packages Token, which can be gathered in the Shopware Account. You can find the token in the Shopware Account under "Shops" > "Licenses" > "..." of one extension and "Install via Composer. +Instead of manually cloning extensions into `custom/plugins`, it's best practice to manage store extensions via Composer. [For more details, see this guide](../../../../guides/hosting/installation-updates/extension-management.md). + +Migrate locally cloned plugins to Composer-managed extensions: ```bash shopware-cli project autofix composer-plugins ``` + +Benefits of using Composer: + +- Composer knows which extension versions exist and are compatible +- Automatic dependency resolution: Composer handles version compatibility for you +- Automatic updates: easily update extensions to new versions +- Less manual work: no need to manually clone and manage extensions in custom directories + +You need a Shopware Packages Token. Get it from your Shopware Account: "Shops" > "Licenses" > "..." of one extension > "Install via Composer". diff --git a/products/tools/cli/project-commands/build.md b/products/tools/cli/project-commands/build.md index 0a08258c89..cb3c01f037 100644 --- a/products/tools/cli/project-commands/build.md +++ b/products/tools/cli/project-commands/build.md @@ -17,6 +17,8 @@ This command modifies the given directory and deletes files. Make sure you have shopware-cli project ci ``` +One of the most-used commands in the Shopware CLI. After cloning a repository, this command prepares a complete artifact that can be deployed with all dependencies installed and assets compiled. It is widely used in PaaS and SaaS deployments. + ## What does it do? - It runs `composer install` (by default, only installs the production dependencies, use `--with-dev-dependencies` to install the dev dependencies as well) @@ -24,6 +26,19 @@ shopware-cli project ci - Deletes unnecessary files like `node_modules` and many more to save disk space - Deletes source code of compiled assets to save disk space - Merges snippets of extensions to speed up Administration +- Generates a Software Bill of Materials (SBOM) listing all deployed dependencies + +## CI system + +The CI system is detected automatically from the environment, so you don't need to configure anything. + +If you want to override the detection — for example, to disable CI-specific output — pass `--ci`: + +```bash +shopware-cli project ci --ci none +``` + +Accepted values: `github`, `gitlab`, `none`. ## Using private Composer repositories @@ -100,6 +115,17 @@ When MJML compilation is enabled: MJML compilation requires the `mjml` package to be installed via NPM in your build environment. The CLI uses local compilation to convert MJML templates to HTML. +## Software Bill of Materials (SBOM) + +The `project ci` command automatically generates a Software Bill of Materials (SBOM) file containing a list of all dependencies installed in your project. This file is useful for: + +- **Docker images**: Container scanning tools can read SBOM files to identify dependencies and check for vulnerabilities +- **Security scanning**: Understand exactly which packages and versions are deployed in production +- **Compliance tracking**: Document all software components in your deployment artifact +- **Supply chain security**: Maintain a record of what's included in each release + +The SBOM is included in the build artifact automatically and can be consumed by tools like Grype and other container security scanners. + ## Build Hooks Build hooks let you run custom shell commands at specific stages of the CI build process. This is useful for tasks like generating configuration files, running custom build steps, or integrating with external tools. diff --git a/products/tools/cli/project-commands/helper-commands.md b/products/tools/cli/project-commands/helper-commands.md index 71ee0f5de0..8ab49fc3ac 100644 --- a/products/tools/cli/project-commands/helper-commands.md +++ b/products/tools/cli/project-commands/helper-commands.md @@ -25,6 +25,14 @@ shopware-cli project create The version parameter can be also `latest` for the latest stable version or `dev-trunk` for the latest development version. +For older Shopware versions with known security vulnerabilities, it is possible to use `--no-audit` to bypass Composer's security advisory blocking: + +```bash +shopware-cli project create --no-audit +``` + +This allows installation of older versions that have known security issues. Use with caution and consider installing the [Shopware Security plugin](https://store.shopware.com/en/swag136939272659f/shopware-6-security-plugin.html) to backport security fixes. + ## Development environment Shopware CLI provides a fully integrated Docker-based development environment. See the [Development Environment](../../../../guides/development/dev-environment.md) guide for the full workflow, or the [CLI command reference](./dev-environment.md) for a quick overview. @@ -53,6 +61,10 @@ Shopware CLI contains replacements for `bin/build-administration.sh` and `bin/bu | bin/watch-storefront.sh | `shopware-cli project storefront-watch` | | bin/watch-administration.sh | `shopware-cli project admin-watch` | +The `admin-build` command runs npm install on first execution, which takes longer initially. Subsequent runs are faster since dependencies are cached. + +The `admin-watch` command: faster than `admin-build` because it monitors changes and rebuilds only what changed. See changes in real-time during development without waiting for a full rebuild. + In addition to the replacements, Shopware CLI allows only watching a specific set of extensions or excluding a few. To only watch specific extensions: @@ -83,13 +95,17 @@ to build only extensions in the `custom/static-plugins` folder of your project, ## Worker -Usually you have to start the worker with `bin/console messenger:consume` in the project root directory. But if you want to have more than one worker at once, it gets a bit tricky. Shopware CLI has a helper command for that: +Starting Messenger workers manually with `bin/console messenger:consume` gets complicated when you need multiple workers running simultaneously. Usually you don't want just one: multiple workers handle higher message throughput. + +Shopware CLI provides a wrapper to easily start multiple workers: ```bash shopware-cli project worker ``` -For production, you should let this handle **supervisord** or **systemd**. But for development, this is a quick way to start multiple workers. +For example, start three workers: `shopware-cli project worker 3` + +For production: use **supervisord** or **systemd** for process management. For development: quick way to spawn multiple workers without manual setup. Widely used by [Shopware PaaS](../../../paas/shopware-paas/). ## Clear cache @@ -113,16 +129,83 @@ A shorter `swx` alias is also available. See [Running Shopware commands](../../. ## Admin API -If you want to make requests against the Shopware-API using curl, you need to get a JWT token and add it as a header. Shopware CLI has a helper command for that: +The `project admin-api` command is a pre-authenticated curl wrapper for the Shopware Admin API. Instead of manually handling JWT token generation and headers, this command handles authentication automatically: + +```bash +shopware-cli project admin-api GET /_info/version +shopware-cli project admin-api POST /api/search/product -d '{"limit":10}' +``` + +It works like curl with the same flags (`-d` for data, `-H` for headers, etc.), but pre-authenticated. This is especially useful for bash scripting and automation where getting curl authentication working can be complex. + +To extract the JWT token for use in other scripts: ```bash shopware-cli project admin-api --output-token ``` -This will output the JWT token to the console. You can also make directly API requests like: +This outputs the token that you can use in your own curl commands or scripts. + +## Project validation + +To validate your entire Shopware project and all its extensions, use: ```bash -shopware-cli project admin-api GET /_info/version +shopware-cli project validate +``` + +This runs validation checks on all extensions in your project. Available flags: + +```bash +shopware-cli project validate --reporter json +shopware-cli project validate --only phpstan +shopware-cli project validate --exclude rector +``` + +See [Validation](../validation.md) for more details on validation tools. + +## Project diagnostics + +The `doctor` command checks your Shopware project for common issues and problems: + +```bash +shopware-cli project doctor +``` + +This is useful when you encounter problems with your setup and need to understand what might be configured improperly. The output provides information about your environment and project configuration. + +## Project configuration schema + +To view the JSON schema for the `.shopware-project.yml` configuration file: + +```bash +shopware-cli project config-schema +``` + +This outputs the JSON schema describing all available configuration options in `.shopware-project.yml`. Useful for automation and understanding the project configuration structure. + +## Initialize project configuration + +To create a new `.shopware-project.yml` configuration file interactively: + +```bash +shopware-cli project config init +``` + +This generates a basic configuration file for your Shopware project. The file is also referenced in development environment setup and deployment configurations. + +## Generate JWT secret + +```bash +shopware-cli project generate-jwt +``` + +Generates new JWT secret keys (private and public) and stores them in `/config/jwt/`. Required only for Shopware versions before 6.5; in 6.5+, JWT secrets are generated automatically. + +Output as environment variables: + +```bash +shopware-cli project generate-jwt --env ``` -You can also pass more options like `-d` for data or `-H` for headers as you would do with curl. +This outputs keys as `JWT_PRIVATE_KEY` and `JWT_PUBLIC_KEY` environment variables (base64-encoded), useful for CI/CD environments. diff --git a/products/tools/cli/project-commands/image-proxy.md b/products/tools/cli/project-commands/image-proxy.md index d428052e96..14e0b39ffe 100644 --- a/products/tools/cli/project-commands/image-proxy.md +++ b/products/tools/cli/project-commands/image-proxy.md @@ -6,9 +6,16 @@ nav: # Image Proxy -The `shopware-cli project image-proxy` command starts a local HTTP server that serves static files from your Shopware project's `public` folder. When a requested file is not found locally, it automatically proxies the request to an upstream server and caches the response for future requests. +The `shopware-cli project image-proxy` command solves a common development problem: when you clone a production database to your local machine, you get 404 errors for product images because you don't have the actual image files. Downloading the entire media library (often 100GB+) is impractical for local development. -This is particularly useful during development when you want to work with a local Shopware installation but need access to media files (images, documents, etc.) from a production or staging environment without downloading the entire media library. +The image proxy starts a local HTTP server that: + +- Intercepts image requests from Shopware +- Checks local cache first +- Fetches missing images from your production server on-demand +- Caches them locally for future requests + +This lets you develop with production-like data and images without needing to download and store the entire media library. ## Usage @@ -19,7 +26,7 @@ shopware-cli project image-proxy # Specify a custom upstream URL shopware-cli project image-proxy --url https://my-shop.com -# Use a different port +# Use a different port (when default 8080 is blocked or in use) shopware-cli project image-proxy --port 3000 # Clear the cache before starting diff --git a/products/tools/cli/project-commands/mysql-dump.md b/products/tools/cli/project-commands/mysql-dump.md index 8c62011755..526bf897e6 100644 --- a/products/tools/cli/project-commands/mysql-dump.md +++ b/products/tools/cli/project-commands/mysql-dump.md @@ -33,11 +33,19 @@ By default, Shopware CLI will try to lock the table before dumping the data. Thi ## Anonymizing data -The `--anonymize` flag will anonymize known user data tables. The following tables are anonymized: +The `--anonymize` flag will anonymize known user data tables. This is widely used to make production database dumps safe for local development: -[See here for the complete list](https://github.com/shopware/shopware-cli/blob/main/internal/shop/config.go#L246) +```bash +shopware-cli project dump --anonymize +``` + +Production databases can be very large (100GB+ of MySQL data), making it impractical to use complete unmodified production data locally. The `--anonymize` flag removes sensitive customer information while preserving database structure and relationships for realistic local testing. + +The following tables are anonymized: + +[Find the complete list here](https://github.com/shopware/shopware-cli/blob/main/internal/shop/config.go#L246) -It is possible to customize the anonymization process by using the `dump.rewrite` configuration in the `shopware-cli.yml` file. +It is possible to customize the anonymization process by using the `dump.rewrite` configuration in the `.shopware-project.yml` file. ```yaml # .shopware-project.yml diff --git a/products/tools/cli/project-commands/remote-extension-management.md b/products/tools/cli/project-commands/remote-extension-management.md index 88317007c0..dbb0e9a1a0 100644 --- a/products/tools/cli/project-commands/remote-extension-management.md +++ b/products/tools/cli/project-commands/remote-extension-management.md @@ -7,7 +7,9 @@ nav: # Remote Extension Management -Shopware CLI has an extension manager to install and manage extensions in your Shopware project through the Shopware API like the Extension Manager in the Shopware 6 Administration panel, but for the CLI. +Shopware CLI provides a CLI wrapper around Shopware's built-in extension management commands. It lets you install, manage, and control extensions in your Shopware project through the Shopware API—with the same capabilities as the Extension Manager in the Shopware 6 Administration panel, but automation-friendly from the CLI. + +This is one of the most commonly used command families in Shopware CLI, especially with Shopware SaaS customers who use it to automate extension uploads and lifecycle management directly to their hosted shops without needing the Admin UI. ::: info This functionality was designed for Shopware SaaS and should not be used for self-hosted installations. [The recommendation is to use the Deployment Helper and install all plugins via Composer](../../../../guides/hosting/installation-updates/deployments/deployment-helper.md) @@ -68,3 +70,19 @@ Deletes an extension from the Shopware instance. ```bash shopware-cli project extension delete ``` + +### Activate extension + +Activates an installed extension in the Shopware instance. + +```bash +shopware-cli project extension activate +``` + +### Deactivate extension + +Deactivates an installed extension in the Shopware instance. + +```bash +shopware-cli project extension deactivate +``` diff --git a/products/tools/cli/shopware-account-commands/authentication.md b/products/tools/cli/shopware-account-commands/authentication.md index 9a123ff676..5a6faace20 100644 --- a/products/tools/cli/shopware-account-commands/authentication.md +++ b/products/tools/cli/shopware-account-commands/authentication.md @@ -15,4 +15,26 @@ shopware-cli account login A browser window will open for you to log in. +## Logout + +To log out from the Shopware Account: + +```bash +shopware-cli account logout +``` + +This removes your stored credentials from the CLI. + +## CI/CD authentication + For CI/CD pipelines, pass `SHOPWARE_CLI_ACCOUNT_CLIENT_ID` and `SHOPWARE_CLI_ACCOUNT_CLIENT_SECRET` as environment variables and directly call the command you want to use. The client ID and client secret can be generated in the **Extension Partner** section under the [Development](https://account.shopware.com/producer/development) navigation point in the [Shopware Account](https://account.shopware.com). + +## List extensions in producer account + +To list all extensions in your producer account (across all projects and versions): + +```bash +shopware-cli account producer extension list +``` + +This displays all extensions you have in the Shopware Store, including their names, versions, and status. This is useful for scripts and automation that need to query your store account. diff --git a/products/tools/cli/shopware-account-commands/configure-composer-repository.md b/products/tools/cli/shopware-account-commands/configure-composer-repository.md index 1f5fda2d4f..a09582c58d 100644 --- a/products/tools/cli/shopware-account-commands/configure-composer-repository.md +++ b/products/tools/cli/shopware-account-commands/configure-composer-repository.md @@ -5,26 +5,37 @@ nav: --- -# Configure composer repository +# Configure Composer repository -To install extensions from the Shopware Store, you need to configure the Composer repository in your `composer.json` file. Shopware CLI can configure this for you automatically. +To install extensions from the Shopware Store, you need to configure Composer with authentication credentials for your store account. -First, make sure you have access to the given Shop in Shopware Account. You can check this with the following command: +## Authenticate with Shopware Account + +First, log in to your Shopware Account: ```bash -shopware-cli account merchant shop list +shopware-cli account login ``` -If you don't see the shop you want to use, you need to switch to the correct company with the following command. Check the [Authentication](./authentication.md) guide for more information. +This stores your credentials locally. See the [Authentication](./authentication.md) guide for more information. -To create a `auth.json` file with the Composer repository configuration, you can use the following command: +## Configure with Shopware Packages token -::: info -You can also use the tab completion in the terminal to get the domains of the shops you have access to. -::: +Create an `auth.json` file in your project root with your Shopware Packages token: -```bash -shopware-cli account merchant shop configure-composer +```json +{ + "http-basic": { + "packages.shopware.com": { + "username": "token", + "password": "" + } + } +} ``` -This will create `auth.json` and append the Composer repository configuration to your `composer.json` file. +Get your Shopware Packages token from your Shopware Account: "Shops" > "Licenses" > "..." of one extension > "Install via Composer". + +::: warning +Keep `auth.json` out of version control. Add it to `.gitignore` to avoid committing credentials to your repository. +::: diff --git a/products/tools/cli/shopware-account-commands/releasing-extension-to-shopware-store.md b/products/tools/cli/shopware-account-commands/releasing-extension-to-shopware-store.md index b311fd6cb8..f617fde6cf 100644 --- a/products/tools/cli/shopware-account-commands/releasing-extension-to-shopware-store.md +++ b/products/tools/cli/shopware-account-commands/releasing-extension-to-shopware-store.md @@ -16,12 +16,20 @@ nav: ## Releasing the extension -To release the extension to the Shopware Store, you need to upload the zip file to the store. This can be done with the `shopware-cli account producer extension upload` command. +To release the extension to the Shopware Store, upload the ZIP file using the `shopware-cli account producer extension upload` command. This is primarily designed for CI/CD pipelines to automate extension releases: ```bash shopware-cli account producer extension upload ``` -This command will check first if an extension with the same version already exists in the store. If not, it will upload the extension to the store. For the compatibility of the extension, the command will use the Composer constraint of `composer.json` or `manifest.xml` file. +The upload process: -After the upload, the command will wait for the result of the automatic validation. This can take a few minutes. If the validation fails, the command will output the error message, and you need to fix the issue and upload the extension again. You can skip this check with the `--skip-for-review-result` option. +1. Checks for existing version: Verifies no extension with the same version already exists in the store +2. Uploads the package: Sends your ZIP file to the Shopware Store +3. Determines compatibility: Uses the Composer constraint from `composer.json` or `manifest.xml` +4. Waits for code review: The command automatically waits for the Store's automatic code review to complete (may take several minutes) +5. Reports results: Shows whether the code review passed or failed + +If the code review fails, fix the issues and upload again. You can skip waiting for the review result with the `--skip-for-review-result` option if needed for CI/CD workflows that handle results separately. + +This workflow means you don't need to use the Shopware Store Admin UI at all—your CI/CD pipeline can handle the entire release process automatically. diff --git a/products/tools/cli/shopware-account-commands/updating-store-page.md b/products/tools/cli/shopware-account-commands/updating-store-page.md index 94ea7d2026..c73979556a 100644 --- a/products/tools/cli/shopware-account-commands/updating-store-page.md +++ b/products/tools/cli/shopware-account-commands/updating-store-page.md @@ -23,7 +23,18 @@ shopware-cli account producer extension info pull This will download all uploaded Store images and create a `.shopware-extension.yml` with all metadata of the extension. -This file can be checked in into the version control and will be automatically removed when you create a zip file using Shopware CLI. +This file can be checked into version control and will be automatically removed when you create a zip file using Shopware CLI. + +## Managing metadata locally with Git + +The `.shopware-extension.yml` file contains all your extension's Store metadata (description, tags, installation instructions, images). By checking this file into Git, you can: + +- Track changes to your Store page like you track code +- Review and approve Store page updates via pull requests +- Automate Store page updates as part of your CI/CD pipeline +- Use AI tools to generate tags and installation descriptions for marketing + +For example, you can use AI to generate appropriate tags for the Shopware Store or write clear installation instructions based on your extension's features. ## Updating the Store page @@ -35,6 +46,10 @@ shopware-cli account producer extension info push This will upload all images and metadata to the Store page. +::: warning +Changes pushed with `info push` go **live immediately** to the Shopware Store and are visible to all users. The Store page cache refreshes every 6 hours, so any mistakes will be visible for that duration. Make sure your changes are correct before pushing. +::: + ## Image configuration Images can be uploaded in two ways: diff --git a/products/tools/cli/validation.md b/products/tools/cli/validation.md index 790107a21f..a2dea582d2 100644 --- a/products/tools/cli/validation.md +++ b/products/tools/cli/validation.md @@ -65,7 +65,7 @@ These versions don't need to be installed locally; they are downloaded on demand ## Running all validation tools -By default, only a few tools are run, but you can run all tools by using the `--full` option. This will run all available tools and check your extension against the latest Shopware version. +By default, validate runs basic checks: extension metadata, some linting, and common mistakes. Use the `--full` option to run comprehensive checks with all available tools: phpstan for PHP static analysis, ESLint for JavaScript, and more. This will thoroughly validate your extension against the latest Shopware version. @@ -91,7 +91,13 @@ shopware-cli extension validate --full /path/to/your/extension -By default, it will check against the latest allowed Shopware version according to your constraints in `composer.json`. It's recommended to run the check against the lowest and highest allowed version, so you can be sure that your extension is compatible with all versions. You can do this by using the `--check-against` option: +By default, it will check against the latest allowed Shopware version according to your constraints in `composer.json`. + +:::info +It's recommended to run the check against the lowest and highest allowed version, so you can be sure that your extension is compatible with all versions. This is critical because extensions often pass validation on the latest version but fail on the lowest supported version due to API changes and deprecations. +::: + +You can do this by using the `--check-against` option: