feat: adjust default config path while preserving backwards compatibility

.github/workflows/schema-pages.yml

@@ -70,8 +70,8 @@ jobs:
             <p>Latest release: <code>${VERSION}</code></p>
             <ul>
               <li><a href="version.json">version.json</a> &mdash; latest CLI version</li>
-              <li><a href="shopware-project-schema.json">shopware-project-schema.json</a> &mdash; schema for <code>.shopware-project.yml</code></li>
-              <li><a href="shopware-extension-schema.json">shopware-extension-schema.json</a> &mdash; schema for <code>.shopware-extension.yml</code></li>
+              <li><a href="shopware-project-schema.json">shopware-project-schema.json</a> &mdash; schema for <code>.config/shopware-project.yml</code></li>
+              <li><a href="shopware-extension-schema.json">shopware-extension-schema.json</a> &mdash; schema for <code>.config/shopware-extension.yml</code></li>
             </ul>
           </body>
           </html>

.github/workflows/smoke-test.yml

@@ -114,10 +114,10 @@ jobs:
       - name: Project config targets environments.local only
         working-directory: shopware-docker
         run: |
-          cat .shopware-project.yml
-          grep -q 'type: docker' .shopware-project.yml
+          cat .config/shopware-project.yml
+          grep -q 'type: docker' .config/shopware-project.yml
           # A top-level url sits at column 0; the environment one is indented.
-          if grep -q '^url:' .shopware-project.yml; then
+          if grep -q '^url:' .config/shopware-project.yml; then
             echo "::error::project create wrote a deprecated top-level url"
             exit 1
           fi

.gitignore

@@ -9,6 +9,8 @@ dist/
 /.shopware-cli
 /.shopware-project.yml
 /.shopware-project.yaml
+/.config/shopware-project.yml
+/.config/shopware-extension.yml
 /test-app
 /go-shopware-admin-api-sdk
 /*.zip

AGENTS.md

@@ -44,8 +44,8 @@ Extension detection is automatic based on file presence. Each type has specific
 
 ### Configuration Files
 - **`.shopware-cli.yaml`** - Global CLI configuration
-- **`.shopware-extension.yml`** - Extension-specific settings (schema: `internal/extension/config_schema.json`, embedded and exposed via `shopware-cli extension config-schema`)
-- **`.shopware-project.yml`** - Project-specific settings (schema: `internal/shop/config_schema.json`, embedded and exposed via `shopware-cli project config-schema`). Shop URL and Admin API credentials belong under `environments`; empty `-e` defaults to `environments.local`. Top-level `url` / `admin_api` are deprecated. An environment's `type` is `local`, `docker`, or `ssh`; `ssh` targets point at a remote host via `ssh.host`/`ssh.user`/`ssh.directory` and run commands through a multiplexed SSH connection (database connections are tunneled automatically).
+- **`.config/shopware-extension.yml` / `.shopware-extension.yml` / `.shopware-extension.yaml`** - Extension-specific settings (schema: `internal/extension/config_schema.json`, embedded and exposed via `shopware-cli extension config-schema`). Only one file is loaded and the first is preferred / used for new projects, the others are legacy and still supported
+- **`.config/shopware-project.yml` / `.shopware-project.yaml` / `.shopware-project.yml`** - Project-specific settings (schema: `internal/shop/config_schema.json`, embedded and exposed via `shopware-cli project config-schema`). Shop URL and Admin API credentials belong under `environments`; empty `-e` defaults to `environments.local`. Top-level `url` / `admin_api` are deprecated. An environment's `type` is `local`, `docker`, or `ssh`; `ssh` targets point at a remote host via `ssh.host`/`ssh.user`/`ssh.directory` and run commands through a multiplexed SSH connection (database connections are tunneled automatically). Only one file is loaded and the first is preferred / used for new projects, the others are legacy and still supported
 
 ## Development Patterns
 

README.md

@@ -84,7 +84,7 @@ shopware-cli --no-update-hint
 
 ## Configuration
 
-Shop URL and Admin API credentials belong under named `environments` in `.shopware-project.yml`. Project-level keys such as `build`, `dump`, `docker`, and `php_version` stay at the top level.
+Shop URL and Admin API credentials belong under named `environments` in `.config/shopware-project.yml`. Project-level keys such as `build`, `dump`, `docker`, and `php_version` stay at the top level.
 
 ```yaml
 environments:

architecture.md

@@ -58,7 +58,7 @@ The `Extension` interface abstracts extension type behind `GetName/GetType/GetSo
 
 ### 2.4 Config schema: one field to add, embedded, self-validating
 
-In the CLI, the config YAML files (`.shopware-extension.yml` / `.shopware-project.yml`) are validated against a built-in schema, and that schema is published via `config-schema` so editors and agents can read the rules and introspect the contract. Adding a config option means adding a field (+ schema where needed) in `internal/extension/config.go` / `internal/shop/config.go`.
+In the CLI, the config YAML files (`.config/shopware-extension.yml` / `.config/shopware-project.yml`) are validated against a built-in schema, and that schema is published via `config-schema` so editors and agents can read the rules and introspect the contract. Adding a config option means adding a field (+ schema where needed) in `internal/extension/config.go` / `internal/shop/config.go`.
 
 Deployment Helper re-parses this same `deployment:` block by hand rather than from the schema.
 
@@ -149,7 +149,7 @@ shopware-cli is the tool you run locally and in CI to build, develop, and packag
 
 In code, this boundary is maintained like so:
 
-- The project config (`.shopware-project.yml`) has a `deployment:` section `ConfigDeployment` covering hooks, extension management, one-time tasks, and staging (internal/shop/config.go:329). The CLI defines and validates that section, but nothing in the CLI ever runs it: only the struct and its schema touch it. The CLI writes the instructions, and Deployment Helper carries them out. Keep it declarative-only on the CLI side.
+- The project config (`.config/shopware-project.yml`) has a `deployment:` section `ConfigDeployment` covering hooks, extension management, one-time tasks, and staging (internal/shop/config.go:329). The CLI defines and validates that section, but nothing in the CLI ever runs it: only the struct and its schema touch it. The CLI writes the instructions, and Deployment Helper carries them out. Keep it declarative-only on the CLI side.
 - Every project the CLI scaffolds automatically pulls in Deployment Helper as a dependency (`require shopware/deployment-helper`, internal/packagist/project_composer_json.go:64).
 - The CI files that the CLI generates (`internal/ci`, covering both GitHub Actions and GitLab) hand the actual deploy to Deployment Helper: The GitHub Actions deploy job `github-deploy.yml` calls `shopware/github-actions/project-deployer`; the `deploy.php` recipe calls `vendor/bin/shopware-deployment-helper run` (Deployer task).
 

cmd/extension/extension_admin_watch.go

@@ -62,7 +62,8 @@ var extensionAdminWatchCmd = &cobra.Command{
 		for _, extensionPath := range args[:len(args)-1] {
 			ext, err := extension.GetExtensionByFolder(cmd.Context(), extensionPath)
 			if err != nil {
-				shopCfg, err := shop.ReadConfig(cmd.Context(), path.Join(extensionPath, shop.DefaultConfigFileName()), true)
+				actualProjectConfigPath := shop.SearchConfigPath(cmd.Context(), extensionPath, "")
+				shopCfg, err := shop.ReadConfig(cmd.Context(), actualProjectConfigPath, true)
 				if err != nil {
 					return err
 				}

cmd/extension/extension_config_init.go

@@ -14,8 +14,8 @@ import (
 
 var extensionConfigInitCmd = &cobra.Command{
 	Use:   "init [path]",
-	Short: "Create a minimal .shopware-extension.yml",
-	Long: `Create a minimal .shopware-extension.yml for an extension checkout.
+	Short: "Create a minimal .config/shopware-extension.yml",
+	Long: `Create a minimal .config/shopware-extension.yml for an extension checkout.
 
 Writes the yaml-language-server schema comment and today's compatibility_date.
 All other configuration keys are optional — add what you need
@@ -39,12 +39,13 @@ Examples:
 
 		force, _ := cmd.Flags().GetBool("force")
 
-		if !force && extension.ConfigExists(abs) && system.IsInteractionEnabled(cmd.Context()) {
+		existing := extension.ConfigPath(cmd.Context(), abs)
+		if !force && existing != "" && system.IsInteractionEnabled(cmd.Context()) {
 			overwrite := false
 			form := huh.NewForm(
 				huh.NewGroup(
 					huh.NewConfirm().
-						Title(extension.ConfigFileName + " already exists. Overwrite?").
+						Title(existing + " already exists. Overwrite?").
 						Value(&overwrite),
 				),
 			)
@@ -57,7 +58,7 @@ Examples:
 			force = true
 		}
 
-		path, err := extension.InitConfig(abs, force)
+		path, err := extension.InitConfig(cmd.Context(), abs, force)
 		if err != nil {
 			return err
 		}
@@ -71,5 +72,5 @@ Examples:
 func init() {
 	extensionConfigCmd.AddCommand(extensionConfigInitCmd)
 
-	extensionConfigInitCmd.Flags().Bool("force", false, "Overwrite existing .shopware-extension.yml")
+	extensionConfigInitCmd.Flags().Bool("force", false, "Overwrite existing .config/shopware-extension.yml")
 }

cmd/project/ci.go

@@ -33,7 +33,8 @@ var projectCI = &cobra.Command{
 			return err
 		}
 
-		shopCfg, err := shop.ReadConfig(cmd.Context(), projectConfigPath, true)
+		actualProjectConfigPath := shop.SearchConfigPath(cmd.Context(), ".", projectConfigPath)
+		shopCfg, err := shop.ReadConfig(cmd.Context(), actualProjectConfigPath, true)
 		if err != nil {
 			return err
 		}

cmd/project/executor.go

@@ -11,7 +11,8 @@ import (
 
 // resolveExecutor returns the Executor for the current environment.
 func resolveExecutor(cmd *cobra.Command, projectRoot string) (executor.Executor, error) {
-	cfg, err := shop.ReadConfig(cmd.Context(), projectConfigPath, true)
+	actualProjectConfigPath := shop.SearchConfigPath(cmd.Context(), projectRoot, projectConfigPath)
+	cfg, err := shop.ReadConfig(cmd.Context(), actualProjectConfigPath, true)
 	if err != nil {
 		return nil, err
 	}

cmd/project/project.go

@@ -2,8 +2,6 @@ package project
 
 import (
 	"github.com/spf13/cobra"
-
-	"github.com/shopware/shopware-cli/internal/shop"
 )
 
 var (
@@ -20,6 +18,6 @@ var projectRootCmd = &cobra.Command{
 
 func Register(rootCmd *cobra.Command) {
 	rootCmd.AddCommand(projectRootCmd)
-	projectRootCmd.PersistentFlags().StringVar(&projectConfigPath, "project-config", shop.DefaultConfigFileName(), "Path to the project config file")
+	projectRootCmd.PersistentFlags().StringVar(&projectConfigPath, "project-config", "", "Path to config, if empty searches default location .config/shopware-project.yml first with legacy fallbacks for .shopware-project.yaml and .shopware-project.yml")
 	projectRootCmd.PersistentFlags().StringVarP(&environmentName, "env", "e", "", environmentFlagUsage)
 }

cmd/project/project_admin_build.go

@@ -31,7 +31,8 @@ var projectAdminBuildCmd = &cobra.Command{
 			return err
 		}
 
-		shopCfg, err := shop.ReadConfig(cmd.Context(), projectConfigPath, true)
+		actualProjectConfigPath := shop.SearchConfigPath(cmd.Context(), projectRoot, projectConfigPath)
+		shopCfg, err := shop.ReadConfig(cmd.Context(), actualProjectConfigPath, true)
 		if err != nil {
 			return err
 		}

cmd/project/project_admin_watch.go

@@ -32,7 +32,8 @@ var projectAdminWatchCmd = &cobra.Command{
 			return err
 		}
 
-		shopCfg, err := shop.ReadConfig(cmd.Context(), projectConfigPath, true)
+		actualProjectConfigPath := shop.SearchConfigPath(cmd.Context(), projectRoot, projectConfigPath)
+		shopCfg, err := shop.ReadConfig(cmd.Context(), actualProjectConfigPath, true)
 		if err != nil {
 			return err
 		}

cmd/project/project_config_init.go

@@ -2,6 +2,7 @@ package project
 
 import (
 	"errors"
+	"os"
 
 	"charm.land/huh/v2"
 	"github.com/spf13/cobra"
@@ -14,8 +15,8 @@ import (
 
 var projectConfigInitCmd = &cobra.Command{
 	Use:   "init",
-	Short: "Create a project config in the current directory",
-	Long: `Creates a new .shopware-project.yml in the current directory.
+	Short: "Creates a new project config",
+	Long: `Creates a new .config/shopware-project.yml config in the current directory.
 
 Shop URL and Admin API credentials are written under environments.local.
 Omit -e / --env on later commands to target that environment.`,
@@ -24,6 +25,13 @@ Omit -e / --env on later commands to target that environment.`,
 			return errors.New("this command requires interaction, but interaction is disabled")
 		}
 
+		// first check if a config already exists
+		actualProjectConfigPath := shop.SearchConfigPath(cmd.Context(), ".", projectConfigPath)
+		_, err := os.Stat(actualProjectConfigPath)
+		if err == nil {
+			return errors.New("a config already exists under " + actualProjectConfigPath)
+		}
+
 		config := &shop.Config{
 			CompatibilityDate: compatibility.DefaultDate(),
 		}
@@ -36,7 +44,7 @@ Omit -e / --env on later commands to target that environment.`,
 			return err
 		}
 
-		logging.FromContext(cmd.Context()).Info("Created .shopware-project.yml")
+		logging.FromContext(cmd.Context()).Info("Created .config/shopware-project.yml")
 
 		return nil
 	},

cmd/project/project_config_schema.go

@@ -8,7 +8,7 @@ import (
 
 var projectConfigSchemaCmd = &cobra.Command{
 	Use:   "config-schema",
-	Short: "Print the JSON schema for .shopware-project.yml",
+	Short: "Print the JSON schema for .config/shopware-project.yml",
 	RunE: func(cmd *cobra.Command, _ []string) error {
 		_, err := cmd.OutOrStdout().Write(shop.ConfigSchema())
 		return err

cmd/project/project_create_form.go

@@ -302,9 +302,9 @@ func runCreateForm(cmd *cobra.Command, opts *createOptions, releases []repositor
 					}, &selectDocker).
 					DescriptionFunc(func() string {
 						if dockerSelected() {
-							return "Select the PHP version of the Docker image (persisted as docker.php.version in .shopware-project.yml)"
+							return "Select the PHP version of the Docker image (persisted as docker.php.version in .config/shopware-project.yml)"
 						}
-						return "Select the PHP used to create and run this project (its version is persisted as php_version in .shopware-project.yml)"
+						return "Select the PHP used to create and run this project (its version is persisted as php_version in .config/shopware-project.yml)"
 					}, &selectDocker).
 					Height(10).
 					OptionsFunc(func() []huh.Option[string] {

cmd/project/project_deployment_package.go

@@ -3,8 +3,6 @@
 package project
 
 import (
-	"path/filepath"
-
 	"github.com/spf13/cobra"
 
 	"github.com/shopware/shopware-cli/internal/shop"
@@ -23,5 +21,5 @@ func packageProjectConfigPath(cmd *cobra.Command, root string) string {
 	if cmd.Flags().Changed("project-config") {
 		return projectConfigPath
 	}
-	return filepath.Join(root, shop.DefaultConfigFileNameInDir(root))
+	return shop.SearchConfigPath(cmd.Context(), root, projectConfigPath)
 }

cmd/project/project_deployment_package_archive_test.go

@@ -126,8 +126,8 @@ deployment:
 			}
 			assert.Equal(t, "built", contents["generated.txt"])
 			assert.NotContains(t, contents, "source.txt")
-			assert.Contains(t, contents[".shopware-project.yml"], "staging:")
-			assert.NotContains(t, contents[".shopware-project.yml"], "environments:")
+			assert.Contains(t, contents[".config/shopware-project.yml"], "staging:")
+			assert.NotContains(t, contents[".config/shopware-project.yml"], "environments:")
 			stage := contents["php-root.txt"]
 			assert.Contains(t, stage, "shopware-deployment-")
 			assert.NoDirExists(t, stage)

cmd/project/project_dev.go

@@ -106,7 +106,8 @@ var projectDevCmd = &cobra.Command{
 			return err
 		}
 
-		cfg, err := shop.ReadConfig(cmd.Context(), projectConfigPath, true)
+		actualProjectConfigPath := shop.SearchConfigPath(cmd.Context(), projectRoot, projectConfigPath)
+		cfg, err := shop.ReadConfig(cmd.Context(), actualProjectConfigPath, true)
 		if err != nil {
 			return err
 		}
@@ -197,9 +198,10 @@ func runMigrationWizardTUI(ctx context.Context, projectRoot string, cfg *shop.Co
 		return err
 	}
 
+	actualProjectConfigPath := shop.SearchConfigPath(ctx, projectRoot, projectConfigPath)
 	_, err = dev.NewMigrationWizardApp(ctx, dev.Options{
 		ProjectRoot: projectRoot,
-		ConfigPath:  projectConfigPath,
+		ConfigPath:  actualProjectConfigPath,
 		Config:      cfg,
 		EnvConfig:   envCfg,
 		Executor:    exec,
@@ -213,7 +215,8 @@ func setupDevEnvironment(cmd *cobra.Command) (*devEnvironment, error) {
 		return nil, err
 	}
 
-	cfg, err := shop.ReadConfig(cmd.Context(), projectConfigPath, true)
+	actualProjectConfigPath := shop.SearchConfigPath(cmd.Context(), projectRoot, projectConfigPath)
+	cfg, err := shop.ReadConfig(cmd.Context(), actualProjectConfigPath, true)
 	if err != nil {
 		return nil, err
 	}
@@ -241,7 +244,7 @@ func newDevEnvironment(cmd *cobra.Command, projectRoot string, cfg *shop.Config)
 	}
 
 	useDocker := exec.Type() == executor.TypeDocker
-	dockerHint := "set the environment " + tui.BoldText.Render("type") + " to " + tui.BoldText.Render("docker") + " in " + tui.BoldText.Render(".shopware-project.yml")
+	dockerHint := "set the environment " + tui.BoldText.Render("type") + " to " + tui.BoldText.Render("docker") + " in " + tui.BoldText.Render(cfg.GetStorageLocation())
 
 	// Docker gets its PHP from the image. Must use the same precedence as the
 	// executor, or the dependencies of a different PHP would be validated.
@@ -270,9 +273,10 @@ func newDevEnvironment(cmd *cobra.Command, projectRoot string, cfg *shop.Config)
 		}
 	}
 
+	actualProjectConfigPath := shop.SearchConfigPath(cmd.Context(), projectRoot, projectConfigPath)
 	return &devEnvironment{
 		projectRoot: projectRoot,
-		configPath:  projectConfigPath,
+		configPath:  actualProjectConfigPath,
 		cfg:         cfg,
 		envCfg:      envCfg,
 		executor:    exec,

cmd/project/project_doctor.go

@@ -36,15 +36,16 @@ var projectDoctor = &cobra.Command{
 		fmt.Println(tui.SectionHeadingStyle.Render("Project"))
 		fmt.Println()
 
-		shopCfg, err := shop.ReadConfig(cmd.Context(), projectConfigPath, true)
+		actualProjectConfigPath := shop.SearchConfigPath(cmd.Context(), projectDir, projectConfigPath)
+		shopCfg, err := shop.ReadConfig(cmd.Context(), actualProjectConfigPath, true)
 		if err != nil {
 			return err
 		}
 
 		if shopCfg.IsFallback() {
 			fmt.Printf("%s Project config: %s\n", tui.CheckWarn, tui.SecondaryText.Render("not found, using fallback"))
 		} else {
-			fmt.Printf("%s Project config: %s\n", tui.CheckOK, tui.GreenText.Render(shop.DefaultConfigFileName()))
+			fmt.Printf("%s Project config: %s\n", tui.CheckOK, tui.GreenText.Render(actualProjectConfigPath))
 		}
 
 		shopwareConstraint, err := extension.GetShopwareProjectConstraint(projectDir)

cmd/project/project_dump.go

@@ -35,7 +35,8 @@ var projectDatabaseDumpCmd = &cobra.Command{
 			return err
 		}
 
-		projectCfg, err := shop.ReadConfig(cmd.Context(), projectConfigPath, true)
+		actualProjectConfigPath := shop.SearchConfigPath(cmd.Context(), ".", projectConfigPath)
+		projectCfg, err := shop.ReadConfig(cmd.Context(), actualProjectConfigPath, true)
 		if err != nil {
 			return err
 		}

cmd/project/project_fix.go

@@ -47,7 +47,7 @@ var projectFixCmd = &cobra.Command{
 
 		only, _ := cmd.Flags().GetString("only")
 
-		toolCfg, err := verifier.GetConfigFromProject(projectPath, false)
+		toolCfg, err := verifier.GetConfigFromProject(cmd.Context(), projectPath, false)
 		if err != nil {
 			return err
 		}

cmd/project/project_format.go

@@ -39,7 +39,7 @@ var projectFormatCmd = &cobra.Command{
 			return fmt.Errorf("cannot find path: %w", err)
 		}
 
-		toolCfg, err := verifier.GetConfigFromProject(projectPath, false)
+		toolCfg, err := verifier.GetConfigFromProject(cmd.Context(), projectPath, false)
 		if err != nil {
 			return err
 		}

cmd/project/project_image_proxy.go

@@ -83,7 +83,8 @@ If a file is not found locally, it proxies the request to the upstream server.`,
 			return err
 		}
 
-		cfg, err := shop.ReadConfig(cmd.Context(), projectConfigPath, true)
+		actualProjectConfigPath := shop.SearchConfigPath(cmd.Context(), path, projectConfigPath)
+		cfg, err := shop.ReadConfig(cmd.Context(), actualProjectConfigPath, true)
 		if err != nil {
 			return err
 		}
@@ -95,7 +96,7 @@ If a file is not found locally, it proxies the request to the upstream server.`,
 		}
 
 		if upstreamURL == "" {
-			return errors.New("upstream URL must be provided either via --url flag or in .shopware-project.yml")
+			return errors.New("upstream URL must be provided either via --url flag or in " + cfg.GetStorageLocation())
 		}
 
 		// Parse upstream URL