(CLI): Allow users define project-path

Author: camilamacedo86

docs/book/src/faq.md

@@ -24,6 +24,20 @@ Then the result resource group will be `mygroup.example.com`.
 
 > If domain field not set, the default value is `my.domain`.
 
+## How can I run Kubebuilder commands on a project in a different directory?
+
+Use the global `--project-path` flag to work on projects without changing directories. This is useful for monorepos or automation.
+
+```shell
+# Initialize project in specific directory
+kubebuilder --project-path=./services/api init --domain example.com
+
+# Create API in different project
+kubebuilder --project-path=./services/api create api --group apps --version v1 --kind MyApp
+```
+
+> The flag works with all project commands but not with `version`, `completion`, or `help`.
+
 ## I'd like to customize my project to use [klog][klog] instead of the [zap][zap] provided by controller-runtime. How to use `klog` or other loggers as the project logger?
 
 In the `main.go` you can replace:

docs/book/src/plugins/available/helm-v2-alpha.md

@@ -481,9 +481,9 @@ The Makefile targets use sensible defaults extracted from your project configura
 
 | Flag                | Description                                                                 |
 |---------------------|-----------------------------------------------------------------------------|
-| **--manifests**     | Path to YAML file containing Kubernetes manifests (default: `dist/install.yaml`) |
-| **--output-dir** string | Output directory for chart (default: `dist`)                                |
-| **--force**         | Regenerates preserved files except `Chart.yaml` (`values.yaml`, `NOTES.txt`, `_helpers.tpl`, `.helmignore`, `test-chart.yml`) |
+| **--manifests**     | Path to your Kubernetes manifests YAML file. Default: `dist/install.yaml`. |
+| **--output-dir**    | Where to create the Helm chart. Default: `dist`. |
+| **--force**         | Recreates all files except `Chart.yaml`. This includes `values.yaml`, `NOTES.txt`, `_helpers.tpl`, `.helmignore`, and `test-chart.yml`. |
 
 <aside class="note" role="note">
 <p class="note-title"> Examples </p>

internal/cli/alpha/generate.go

@@ -43,7 +43,7 @@ func NewScaffoldCommand() *cobra.Command {
 	scaffoldCmd := &cobra.Command{
 		Use:   "generate",
 		Short: "Re-scaffold a Kubebuilder project from its PROJECT file",
-		Long: `The 'generate' command re-creates a Kubebuilder project scaffold based on the configuration 
+		Long: `The 'generate' command re-creates a Kubebuilder project scaffold based on the configuration
 defined in the PROJECT file, using the latest installed Kubebuilder version and plugins.
 
 This is helpful for migrating projects to a newer Kubebuilder layout or plugin version (e.g., v3 to v4)
@@ -52,13 +52,22 @@ as update your project from any previous version to the current one.
 If no output directory is provided, the current working directory will be cleaned (except .git and PROJECT).`,
 		Example: `
   # **WARNING**(will delete all files to allow the re-scaffold except .git and PROJECT)
-  # Re-scaffold the project in-place 
-  kubebuilder alpha generate
+  # Re-scaffold the project in-place (using global --project-path)
+  kubebuilder --project-path="./path/to/project" alpha generate
 
-  # Re-scaffold the project from ./test into ./my-output
-  kubebuilder alpha generate --input-dir="./path/to/project" --output-dir="./my-output"
+  # Re-scaffold into a different output directory
+  kubebuilder --project-path="./path/to/project" alpha generate --output-dir="./my-output"
+
+  # Legacy: using --input-dir (DEPRECATED - use global --project-path instead)
+  kubebuilder alpha generate --input-dir="./path/to/project"
 `,
 		PreRunE: func(_ *cobra.Command, _ []string) error {
+			// Handle deprecation warning
+			if opts.InputDir != "" {
+				slog.Warn("--input-dir is DEPRECATED and will be removed in a future release")
+				slog.Warn("Use the global --project-path flag instead:")
+				slog.Warn("  Example: kubebuilder --project-path=\"./myproject\" alpha generate")
+			}
 			return opts.Validate()
 		},
 		Run: func(_ *cobra.Command, _ []string) {
@@ -70,8 +79,10 @@ If no output directory is provided, the current working directory will be cleane
 	}
 
 	scaffoldCmd.Flags().StringVar(&opts.InputDir, "input-dir", "",
-		"Path to the directory containing the PROJECT file. "+
-			"Defaults to the current working directory. WARNING: delete existing files (except .git and PROJECT).")
+		"[DEPRECATED: use global --project-path instead] "+
+			"Path to the directory containing the PROJECT file.")
+	// Mark the flag as deprecated
+	_ = scaffoldCmd.Flags().MarkDeprecated("input-dir", "use global --project-path flag instead (e.g., kubebuilder --project-path=./path alpha generate)")
 
 	scaffoldCmd.Flags().StringVar(&opts.OutputDir, "output-dir", "",
 		"Directory where the new project scaffold will be written. "+

internal/cli/alpha/internal/generate.go

@@ -49,6 +49,19 @@ var getExecutablePathFunc = getExecutablePath
 
 // Generate handles the migration and scaffolding process.
 func (opts *Generate) Generate() error {
+	// If InputDir is not set, use current working directory.
+	// This handles both:
+	// 1. Legacy --input-dir flag (explicitly sets opts.InputDir)
+	// 2. Global --project-path flag (changes CWD before this runs, opts.InputDir is empty)
+	if opts.InputDir == "" {
+		cwd, err := os.Getwd()
+		if err != nil {
+			return fmt.Errorf("failed to get working directory: %w", err)
+		}
+		opts.InputDir = cwd
+		slog.Info("Using current working directory as input directory", "path", opts.InputDir)
+	}
+
 	projectConfig, err := common.LoadProjectConfig(opts.InputDir)
 	if err != nil {
 		return fmt.Errorf("error loading project config: %v", err)

internal/cli/alpha/internal/generate_test.go

@@ -1103,4 +1103,243 @@ var _ = Describe("Generate", func() {
 			Expect(g.Generate()).To(Succeed())
 		})
 	})
+
+	Context("with global --project-path flag behavior", func() {
+		var projectDir string
+
+		BeforeEach(func() {
+			// Create a separate project directory
+			var err error
+			projectDir, err = os.MkdirTemp("", "alpha-project-path-test-*")
+			Expect(err).NotTo(HaveOccurred())
+
+			// Create PROJECT file in project directory
+			projectFilePath := filepath.Join(projectDir, "PROJECT")
+			projectFileContent := []byte(`domain: example.com
+layout:
+- go.kubebuilder.io/v4
+projectName: test-project
+repo: github.com/example/test-project
+version: "3"
+`)
+			Expect(os.WriteFile(projectFilePath, projectFileContent, 0o644)).To(Succeed())
+		})
+
+		AfterEach(func() {
+			if projectDir != "" {
+				_ = os.RemoveAll(projectDir)
+			}
+		})
+
+		It("should work when CWD is changed to project directory (simulating --project-path)", func() {
+			// Save current directory
+			originalWd, err := os.Getwd()
+			Expect(err).NotTo(HaveOccurred())
+			defer func() {
+				_ = os.Chdir(originalWd)
+			}()
+
+			// Change to project directory (this is what --project-path does)
+			Expect(os.Chdir(projectDir)).To(Succeed())
+
+			// InputDir should be empty when using global --project-path
+			// The Generate function should default to CWD
+			g := &Generate{
+				InputDir:           "", // Empty - will use CWD
+				OutputDir:          filepath.Join(projectDir, "regenerated"),
+				SkipGoVersionCheck: true,
+			}
+
+			// Validate should succeed
+			err = g.Validate()
+			Expect(err).NotTo(HaveOccurred())
+
+			// Verify InputDir gets set to CWD (handle symlink resolution on macOS)
+			expectedDir, err := filepath.EvalSymlinks(projectDir)
+			Expect(err).NotTo(HaveOccurred())
+
+			actualDir, err := filepath.EvalSymlinks(g.InputDir)
+			Expect(err).NotTo(HaveOccurred())
+
+			Expect(actualDir).To(Equal(expectedDir))
+		})
+
+		It("should use CWD when InputDir is empty", func() {
+			// Save current directory
+			originalWd, err := os.Getwd()
+			Expect(err).NotTo(HaveOccurred())
+			defer func() {
+				_ = os.Chdir(originalWd)
+			}()
+
+			// Change to project directory
+			Expect(os.Chdir(projectDir)).To(Succeed())
+
+			// Create Generate with empty InputDir
+			g := &Generate{
+				InputDir:           "",
+				SkipGoVersionCheck: true,
+			}
+
+			// Call Generate - it should use CWD as InputDir
+			// Note: This will fail during kubebuilder execution but that's OK,
+			// we're testing that it picks up the right directory
+			_ = g.Generate()
+
+			// Verify that InputDir was set to the current working directory
+			cwd, err := os.Getwd()
+			Expect(err).NotTo(HaveOccurred())
+			Expect(g.InputDir).To(Equal(cwd))
+		})
+
+		It("should load PROJECT file from CWD when InputDir is empty", func() {
+			// Save current directory
+			originalWd, err := os.Getwd()
+			Expect(err).NotTo(HaveOccurred())
+			defer func() {
+				_ = os.Chdir(originalWd)
+			}()
+
+			// Change to project directory
+			Expect(os.Chdir(projectDir)).To(Succeed())
+
+			// Verify PROJECT file can be loaded from CWD
+			_, err = os.Stat("PROJECT")
+			Expect(err).NotTo(HaveOccurred())
+
+			// Verify content
+			content, err := os.ReadFile("PROJECT")
+			Expect(err).NotTo(HaveOccurred())
+			Expect(string(content)).To(ContainSubstring("domain: example.com"))
+			Expect(string(content)).To(ContainSubstring("test-project"))
+		})
+
+		It("should resolve output directory relative to project directory", func() {
+			// Save current directory
+			originalWd, err := os.Getwd()
+			Expect(err).NotTo(HaveOccurred())
+			defer func() {
+				_ = os.Chdir(originalWd)
+			}()
+
+			// Change to project directory
+			Expect(os.Chdir(projectDir)).To(Succeed())
+
+			// Create Generate with relative output path
+			g := &Generate{
+				InputDir:           "", // Will use CWD
+				OutputDir:          "regenerated",
+				SkipGoVersionCheck: true,
+			}
+
+			// Validate should succeed
+			err = g.Validate()
+			Expect(err).NotTo(HaveOccurred())
+
+			// Verify paths are resolved correctly
+			expectedInputDir, err := filepath.EvalSymlinks(projectDir)
+			Expect(err).NotTo(HaveOccurred())
+
+			actualInputDir, err := filepath.EvalSymlinks(g.InputDir)
+			Expect(err).NotTo(HaveOccurred())
+
+			Expect(actualInputDir).To(Equal(expectedInputDir))
+		})
+
+		It("should handle absolute output directory path", func() {
+			// Save current directory
+			originalWd, err := os.Getwd()
+			Expect(err).NotTo(HaveOccurred())
+			defer func() {
+				_ = os.Chdir(originalWd)
+			}()
+
+			// Create separate output directory
+			outputDir, err := os.MkdirTemp("", "alpha-output-*")
+			Expect(err).NotTo(HaveOccurred())
+			defer func() {
+				_ = os.RemoveAll(outputDir)
+			}()
+
+			// Change to project directory
+			Expect(os.Chdir(projectDir)).To(Succeed())
+
+			// Create Generate with absolute output path
+			g := &Generate{
+				InputDir:           "", // Will use CWD (project directory)
+				OutputDir:          outputDir,
+				SkipGoVersionCheck: true,
+			}
+
+			// Validate should succeed
+			err = g.Validate()
+			Expect(err).NotTo(HaveOccurred())
+
+			// Verify input is CWD and output is absolute
+			expectedInputDir, err := filepath.EvalSymlinks(projectDir)
+			Expect(err).NotTo(HaveOccurred())
+
+			actualInputDir, err := filepath.EvalSymlinks(g.InputDir)
+			Expect(err).NotTo(HaveOccurred())
+
+			Expect(actualInputDir).To(Equal(expectedInputDir))
+		})
+
+		It("should work with PROJECT file containing multiple resources", func() {
+			// Create PROJECT file with resources
+			projectFileContent := []byte(`domain: example.com
+layout:
+- go.kubebuilder.io/v4
+projectName: test-project
+repo: github.com/example/test-project
+resources:
+- api:
+    crdVersion: v1
+    namespaced: true
+  controller: true
+  domain: example.com
+  group: apps
+  kind: WebApp
+  path: github.com/example/test-project/api/v1
+  version: v1
+- api:
+    crdVersion: v1
+    namespaced: true
+  controller: true
+  domain: example.com
+  group: batch
+  kind: Job
+  path: github.com/example/test-project/api/v1
+  version: v1
+version: "3"
+`)
+			Expect(os.WriteFile(filepath.Join(projectDir, "PROJECT"), projectFileContent, 0o644)).To(Succeed())
+
+			// Save current directory
+			originalWd, err := os.Getwd()
+			Expect(err).NotTo(HaveOccurred())
+			defer func() {
+				_ = os.Chdir(originalWd)
+			}()
+
+			// Change to project directory
+			Expect(os.Chdir(projectDir)).To(Succeed())
+
+			// Verify PROJECT file can be loaded
+			content, err := os.ReadFile("PROJECT")
+			Expect(err).NotTo(HaveOccurred())
+			Expect(string(content)).To(ContainSubstring("WebApp"))
+			Expect(string(content)).To(ContainSubstring("Job"))
+
+			// Create Generate
+			g := &Generate{
+				InputDir:           "",
+				SkipGoVersionCheck: true,
+			}
+
+			// Validate should succeed
+			err = g.Validate()
+			Expect(err).NotTo(HaveOccurred())
+		})
+	})
 })