Adds CLI notes from recent team walk-throughs and discussions

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.

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,23 @@ If your extension is not a plugin but itself a bundle, make sure your composer t
 Now you can use `shopware-cli extension build <path>` 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
+### 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. `<name>-<hash>.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.
+
+## 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
@@ -90,9 +100,9 @@ The command copies the extension to a temporary directory, builds the assets, de
 
 **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:
 
@@ -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 zip <path> --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:
 

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`:

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 <path>
 
 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 <path>
+```
+
+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 <path>
 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.

products/tools/cli/index.md

@@ -67,3 +67,9 @@ COPY --from=ghcr.io/shopware/shopware-cli:bin /shopware-cli /usr/local/bin/shopw
 </Tabs>
 
 **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.

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".

products/tools/cli/project-commands/build.md

@@ -17,13 +17,28 @@
 shopware-cli project ci <path>
 ```
 
+One of the most-used commands in the Shopware CLI. After cloning a repository, this command prepares a complete deployable artifact with all dependencies installed and assets compiled. 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)
 - Looks for missing assets of extensions and only compiles the missing assets to speed up the build process
 - 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 configuration
+
+Specify which CI/CD platform to configure for:
+
+```bash
+shopware-cli project ci <path> --ci github
+shopware-cli project ci <path> --ci gitlab
+shopware-cli project ci <path> --ci none
+```
+
+Options: `github`, `gitlab`, `none` (default).
 
 ## Using private Composer repositories
 
@@ -100,6 +115,17 @@
 
 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, Syft, 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.

products/tools/cli/project-commands/helper-commands.md

@@ -25,6 +25,14 @@ shopware-cli project create <folder-name> <version>
 
 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 <folder-name> <version> --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 <amount>
 ```
 
-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](../../../products/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 misconfigured. 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 <path-to-project>
+```
+
+Generates new JWT secret keys (private and public) and stores them in `<path-to-project>/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.