chore (cli): clarify command and flag help texts

cmd/extension/extension_fix.go

@@ -80,7 +80,7 @@ var extensionFixCmd = &cobra.Command{
 
 func init() {
 	extensionRootCmd.AddCommand(extensionFixCmd)
-	extensionFixCmd.Flags().String("only", "", "Run only specific fixers by name (comma-separated, e.g. eslint,rector)")
-	extensionFixCmd.Flags().String("exclude", "", "Exclude fixers after applying --only (comma-separated, e.g. eslint,rector)")
-	extensionFixCmd.Flags().Bool("allow-non-git", false, "Allow running the fix command on non-git repositories")
+	extensionFixCmd.Flags().String("only", "", "Run only the specified fixers (comma-separated, e.g. eslint,rector)")
+	extensionFixCmd.Flags().String("exclude", "", "Skip these fixers; must be in the --only list if set (comma-separated, e.g. eslint,rector)")
+	extensionFixCmd.Flags().Bool("allow-non-git", false, "Allow fix to run outside a Git repository")
 }

cmd/extension/extension_format.go

@@ -74,7 +74,7 @@ var extensionFormat = &cobra.Command{
 
 func init() {
 	extensionRootCmd.AddCommand(extensionFormat)
-	extensionFormat.Flags().String("only", "", "Run only specific formatters by name (comma-separated, e.g. prettier,php-cs-fixer)")
-	extensionFormat.Flags().String("exclude", "", "Exclude formatters after applying --only (comma-separated, e.g. prettier,php-cs-fixer)")
+	extensionFormat.Flags().String("only", "", "Run only the specified formatters (comma-separated, e.g. prettier,php-cs-fixer)")
+	extensionFormat.Flags().String("exclude", "", "Skip these formatters; must be in the --only list if set (comma-separated, e.g. prettier,php-cs-fixer)")
 	extensionFormat.Flags().Bool("dry-run", false, "Run in dry run mode")
 }

cmd/extension/extension_package.go

@@ -27,6 +27,7 @@ var (
 var extensionPackageCmd = &cobra.Command{
 	Use:     "package path [branch]",
 	Short:   "Build a distributable extension ZIP",
+	Long:    "Build a ZIP of an extension. By default, files come from a clean Git checkout of the current tag or branch, so uncommitted changes are not included; use --disable-git to package the working copy. The build runs in a temporary folder and leaves the extension folder unchanged. The ZIP is named <name>-<tag-or-branch>.zip when a tag or branch is available, or <name>.zip otherwise, unless --filename is set.",
 	Aliases: []string{"zip"},
 	Args:    cobra.RangeArgs(1, 2),
 	RunE: func(cmd *cobra.Command, args []string) error {
@@ -228,17 +229,17 @@ var extensionPackageCmd = &cobra.Command{
 
 func init() {
 	extensionRootCmd.AddCommand(extensionPackageCmd)
-	extensionPackageCmd.Flags().BoolVar(&disableGit, "disable-git", false, "Package the working copy instead of a clean git checkout (symlinks are skipped)")
-	extensionPackageCmd.Flags().BoolVar(&extensionReleaseMode, "release", false, "Prepare a release build (generate the changelog, remove app secrets)")
-	extensionPackageCmd.Flags().String("overwrite-app-backend-url", "", "Change all URLs in manifest.xml to this URL")
-	extensionPackageCmd.Flags().String("overwrite-app-backend-secret", "", "Change the secret to this value")
-	extensionPackageCmd.Flags().String("overwrite-version", "", "Change the extension version to this value")
-	extensionPackageCmd.Flags().Bool("use-git-tag-as-version", false, "Use the detected git tag as the extension version")
+	extensionPackageCmd.Flags().BoolVar(&disableGit, "disable-git", false, "Package the working copy instead of a clean Git checkout (symlinks are skipped)")
+	extensionPackageCmd.Flags().BoolVar(&extensionReleaseMode, "release", false, "Prepare a release build: generate the changelog if enabled and, for apps, remove the secret from manifest.xml")
+	extensionPackageCmd.Flags().String("overwrite-app-backend-url", "", "Replace the scheme and host of the app backend URLs in manifest.xml (apps only)")
+	extensionPackageCmd.Flags().String("overwrite-app-backend-secret", "", "Set the app secret in manifest.xml (apps only)")
+	extensionPackageCmd.Flags().String("overwrite-version", "", "Set the extension version in the package")
+	extensionPackageCmd.Flags().Bool("use-git-tag-as-version", false, "Use the Git tag (without a leading v) as the extension version")
 	extensionPackageCmd.MarkFlagsMutuallyExclusive("use-git-tag-as-version", "disable-git")
 	extensionPackageCmd.MarkFlagsMutuallyExclusive("use-git-tag-as-version", "overwrite-version")
-	extensionPackageCmd.Flags().String("output-directory", "", "Output directory for the zip file")
-	extensionPackageCmd.Flags().String("git-commit", "", "Commit hash or tag to package (defaults to the current tag or branch)")
-	extensionPackageCmd.Flags().String("filename", "", "Name of the zip file, generated from the extension name and tag when not set")
+	extensionPackageCmd.Flags().String("output-directory", "", "Directory for the ZIP file (created if missing)")
+	extensionPackageCmd.Flags().String("git-commit", "", "Git commit hash, tag, or branch to package (default: the current tag or branch)")
+	extensionPackageCmd.Flags().String("filename", "", "Name of the ZIP file (default: <name>-<tag>.zip when tagged, otherwise <name>.zip)")
 }
 
 func getStringOnStringError(val string, _ error) string {

cmd/extension/extension_validate.go

@@ -21,6 +21,7 @@ import (
 var extensionValidateCmd = &cobra.Command{
 	Use:   "validate path",
 	Short: "Validate extension metadata, assets, and code quality",
+	Long:  "Validate an extension folder or ZIP file. With --store-compliance (or SHOPWARE_CLI_STORE_COMPLIANCE=1), the Store's rules apply and the extension's validation.ignore list is not used.",
 	Args:  cobra.ExactArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
 		storeCompliance, _ := cmd.Flags().GetBool("store-compliance")
@@ -104,6 +105,7 @@ var extensionValidateCmd = &cobra.Command{
 			toolCfg.Extension.GetExtensionConfig().Validation.StoreCompliance = true
 			// The user is not allowed to provide a custom ignore list when store compliance is enabled
 			toolCfg.Extension.GetExtensionConfig().Validation.Ignore = extension.ConfigValidationList{}
+			toolCfg.ValidationIgnores = nil
 		}
 
 		toolCfg.CheckAgainst = checkAgainst

cmd/project/ci.go

@@ -17,9 +17,11 @@ import (
 )
 
 var projectCI = &cobra.Command{
-	Use:   "ci",
-	Short: "Create a production build of a Shopware project",
-	Args:  cobra.ExactArgs(1),
+	Use:   "ci path",
+	Short: "Turn a project directory into a production build (removes dev files, adds SBOM)",
+	Long: "Build the given Shopware project directory for production and generate an SBOM. The directory itself is changed: development-only files (tests, Administration sources, source maps, build.cleanup_paths) are removed, and empty placeholders are added so Shopware still runs without them.\n" +
+		"Use it in CI or on a disposable checkout; outside CI it refuses to run with uncommitted changes or untracked files unless --force is passed.",
+	Args: cobra.ExactArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
 		root, err := filepath.Abs(args[0])
 		if err != nil {
@@ -56,8 +58,8 @@ var projectCI = &cobra.Command{
 
 func init() {
 	projectRootCmd.AddCommand(projectCI)
-	projectCI.PersistentFlags().Bool("with-dev-dependencies", false, "Include development dependencies in the build")
-	projectCI.PersistentFlags().Bool("force", false, "Force the CI build despite uncommitted changes")
+	projectCI.PersistentFlags().Bool("with-dev-dependencies", false, "Include Composer dev dependencies in the build")
+	projectCI.PersistentFlags().Bool("force", false, "Run the build outside CI despite uncommitted changes or untracked files")
 }
 
 func projectCISafetyCheck(ctx context.Context, root string, force bool, getenv func(string) string) error {

cmd/project/project_dev.go

@@ -98,7 +98,7 @@ const (
 
 var projectDevCmd = &cobra.Command{
 	Use:   "dev",
-	Short: "Start a project's configured Shopware development environment",
+	Short: "Start the project's development environment and, when run in a terminal, open its terminal dashboard",
 	Long:  "Start the development environment. This launches the interactive TUI dashboard when run in a terminal, or starts the containers in the background otherwise. Requires a Docker environment; local and ssh environments do not manage containers.",
 	RunE: func(cmd *cobra.Command, args []string) error {
 		projectRoot, err := shop.FindClosestShopwareProject(false)
@@ -460,5 +460,5 @@ func init() {
 	projectDevCmd.AddCommand(projectDevStatusCmd)
 
 	projectDevStopCmd.Flags().Bool("remove-data", false, "Remove the named volumes declared in the Compose file, deleting all data stored in them")
-	projectDevCmd.PersistentFlags().String("on-port-conflict", portConflictModeFail, "When host ports are occupied: fail or use random free ports (non-interactive mode; the dashboard prompts instead)")
+	projectDevCmd.PersistentFlags().String("on-port-conflict", portConflictModeFail, "In non-interactive mode, if host ports are in use: fail, or random to pick free ports and save them to the local config (the dashboard asks instead)")
 }

cmd/project/project_fix.go

@@ -15,6 +15,7 @@ import (
 var projectFixCmd = &cobra.Command{
 	Use:   "fix [path]",
 	Short: "Apply code-quality fixes to a project",
+	Long:  "Run code-quality fixers on the project's own code, such as extensions in custom/ and configured bundles, and change the files directly. Packages that Composer installs into vendor/ are not changed. Requires a Git repository so the changes can be reviewed, unless --allow-non-git is passed.",
 	Args:  cobra.MaximumNArgs(1),
 	PreRunE: func(cmd *cobra.Command, args []string) error {
 		return verifier.SetupTools(cmd.Context(), cmd.Root().Version)
@@ -74,5 +75,5 @@ var projectFixCmd = &cobra.Command{
 func init() {
 	projectRootCmd.AddCommand(projectFixCmd)
 	projectFixCmd.PersistentFlags().String("only", "", "Run only the specified fixers (comma-separated, e.g. eslint,rector)")
-	projectFixCmd.PersistentFlags().Bool("allow-non-git", false, "Allow fixes in projects without a Git repository")
+	projectFixCmd.PersistentFlags().Bool("allow-non-git", false, "Allow fix to run outside a Git repository")
 }

cmd/project/project_format.go

@@ -13,7 +13,8 @@ import (
 
 var projectFormatCmd = &cobra.Command{
 	Use:   "format [path]",
-	Short: "Run configured formatters on project files",
+	Short: "Format a project's code with PHP-CS-Fixer and Prettier",
+	Long:  "Format the project's own code, such as extensions in custom/ and configured bundles, and change the files directly. Packages that Composer installs into vendor/ are not changed. PHP-CS-Fixer uses the project's .php-cs-fixer.dist.php if present; Prettier always uses the CLI's own config. Use --dry-run to only report files that would change.",
 	Args:  cobra.MaximumNArgs(1),
 	PreRunE: func(cmd *cobra.Command, args []string) error {
 		return verifier.SetupTools(cmd.Context(), cmd.Root().Version)
@@ -66,5 +67,5 @@ var projectFormatCmd = &cobra.Command{
 func init() {
 	projectRootCmd.AddCommand(projectFormatCmd)
 	projectFormatCmd.PersistentFlags().String("only", "", "Run only the specified formatters (comma-separated, e.g. prettier,php-cs-fixer)")
-	projectFormatCmd.PersistentFlags().Bool("dry-run", false, "Run formatters without changing files")
+	projectFormatCmd.PersistentFlags().Bool("dry-run", false, "Report files that would change, without changing them")
 }

cmd/project/project_validate.go

@@ -18,6 +18,7 @@ import (
 var projectValidateCmd = &cobra.Command{
 	Use:   "validate [path]",
 	Short: "Run static analysis and Shopware checks on a project",
+	Long:  "Validate the project's own code, such as extensions in custom/ and configured bundles. Packages that Composer installs into vendor/ are not validated. Runs on a temporary copy unless --no-copy is passed.",
 	Args:  cobra.MaximumNArgs(1),
 	PreRunE: func(cmd *cobra.Command, args []string) error {
 		if _, err := projectValidationFormat(cmd); err != nil {
@@ -123,11 +124,11 @@ func projectValidationFormat(cmd *cobra.Command) (string, error) {
 
 func init() {
 	projectRootCmd.AddCommand(projectValidateCmd)
-	projectValidateCmd.PersistentFlags().String("format", "", "Validation report format (summary, json, github, gitlab, junit, or markdown)")
+	projectValidateCmd.PersistentFlags().String("format", "", "Report format (summary, json, github, gitlab, junit, markdown; auto-detected if unset)")
 	projectValidateCmd.PersistentFlags().String("reporter", "", "Reporting format (summary, json, github, gitlab, junit, markdown)")
-	projectValidateCmd.PersistentFlags().String("only", "", "Run only the specified tools (comma-separated, e.g. phpstan,eslint)")
-	projectValidateCmd.PersistentFlags().String("exclude", "", "Exclude tools after applying --only; names must be in the selected set (comma-separated, e.g. phpstan,eslint)")
-	projectValidateCmd.PersistentFlags().Bool("no-copy", false, "Validate the project in place instead of copying it to a temporary directory")
+	projectValidateCmd.PersistentFlags().String("only", "", "Run only the specified tools (comma-separated). Available: phpstan, eslint, stylelint, storefront-twig, builtin (legacy alias: sw-cli, deprecated)")
+	projectValidateCmd.PersistentFlags().String("exclude", "", "Skip these tools (comma-separated); with --only, each must be selected there. Names: phpstan, eslint, stylelint, storefront-twig, builtin (legacy alias: sw-cli, deprecated)")
+	projectValidateCmd.PersistentFlags().Bool("no-copy", false, "Validate the project directory itself, not a temporary copy")
 	projectValidateCmd.PersistentFlags().Bool("local-only", false, "Validate only extensions in custom/* folders")
 	projectValidateCmd.MarkFlagsMutuallyExclusive("format", "reporter")
 	_ = projectValidateCmd.PersistentFlags().MarkDeprecated("reporter", "use --format instead")

cmd/project/project_worker.go

@@ -105,7 +105,7 @@ queue. The count per queue is optional and defaults to 1.`,
 
 func init() {
 	projectRootCmd.AddCommand(projectWorkerCmd)
-	projectWorkerCmd.PersistentFlags().Bool("verbose", false, "Enable verbose worker output")
+	projectWorkerCmd.PersistentFlags().Bool("verbose", false, "Show every message the workers handle, plus debug logs")
 	projectWorkerCmd.PersistentFlags().String("queue", "", "Queues to consume (comma-separated)")
 	projectWorkerCmd.PersistentFlags().String("memory-limit", "512M", "Worker memory limit")
 	projectWorkerCmd.PersistentFlags().String("time-limit", "120", "Worker time limit in seconds")

cmd/root.go

@@ -96,9 +96,9 @@ func init() {
 		_ = system.CloseCaches()
 	})
 
-	rootCmd.PersistentFlags().Bool("verbose", false, "Show debug output")
-	rootCmd.PersistentFlags().BoolP("no-interaction", "n", false, "Do not ask any interactive questions")
-	rootCmd.PersistentFlags().Bool("no-update-hint", false, "Do not show update notifications")
+	rootCmd.PersistentFlags().Bool("verbose", false, "Show debug logs and detailed tool output")
+	rootCmd.PersistentFlags().BoolP("no-interaction", "n", false, "Run without prompting; commands use defaults or fail where input is needed")
+	rootCmd.PersistentFlags().Bool("no-update-hint", false, "Skip checking for a newer shopware-cli version")
 
 	project.Register(rootCmd)
 	extension.Register(rootCmd)