Added 'databricks bundle plan' command (#3530)

andrewnester · denik · lennartkats-db · web-flow · commit d78f88fe7b2b · 2025-09-24T12:52:28.000Z
## Changes
Made 'databricks bundle plan' command public (previously hidden)

## Why
This command builds the bundle and displays the actions that will be
performed on the deployed resources without making any changes.
It is useful for previewing changes before running `bundle deploy`.
The output of the command is high level list of actions and resources
which are changed, for example
```
&gt;&gt;&gt; databricks bundle plan

create job.my_project_job
delete job.sample_job
create pipeline.my_project_pipeline
delete pipeline.sample_etl

Plan: 2 to add, 0 to change, 2 to delete, 3 unchanged
```

## Tests
Covered by existing tests

---------

Co-authored-by: Denis Bilenko &lt;denis.bilenko@databricks.com&gt;
Co-authored-by: Lennart Kats (databricks) &lt;lennart.kats@databricks.com&gt;
diff --git a/NEXT_CHANGELOG.md b/NEXT_CHANGELOG.md
@@ -3,12 +3,14 @@
 ## Release v0.270.0
 
 ### Notable Changes
+* Add 'databricks bundle plan' command. This command shows the deployment plan for the current bundle configuration without making any changes. ([#3530](https://github.com/databricks/cli/pull/3530)
 
 ### CLI
 
 ### Dependency updates
 
 ### Bundles
+* Add 'databricks bundle plan' command ([#3530](https://github.com/databricks/cli/pull/3530)
 * Add new Lakeflow Pipelines support for bundle generate ([#3568](https://github.com/databricks/cli/pull/3568))
 * Fix bundle deploy to not update permissions or grants for unbound resources ([#3642](https://github.com/databricks/cli/pull/3642))
 * Introduce new bundle variable: `${workspace.current_user.domain_friendly_name}` ([#3623](https://github.com/databricks/cli/pull/3623))
diff --git a/acceptance/bundle/debug/output.txt b/acceptance/bundle/debug/output.txt
@@ -4,6 +4,7 @@ Usage:
   databricks bundle debug [command]
 
 Available Commands:
+  plan        Show deployment plan in JSON format (experimental)
   refschema   Dump all relevant fields all bundle resources
 
 Flags:
diff --git a/acceptance/bundle/help/bundle/output.txt b/acceptance/bundle/help/bundle/output.txt
@@ -24,6 +24,7 @@ Available Commands:
   generate    Generate bundle configuration
   init        Initialize using a bundle template
   open        Open a resource in the browser
+  plan        Show deployment plan
   run         Run a job, pipeline update or app
   schema      Generate JSON Schema for bundle configuration
   summary     Summarize resources deployed by this bundle
diff --git a/acceptance/bundle/resources/jobs/update/output.txt b/acceptance/bundle/resources/jobs/update/output.txt
@@ -4,7 +4,7 @@ create jobs.foo
 
 Plan: 1 to add, 0 to change, 0 to delete, 0 unchanged
 
->>> [CLI] bundle plan -o json
+>>> [CLI] bundle debug plan
 {
   "plan": {
     "resources.jobs.foo": {
@@ -22,7 +22,7 @@ Deployment complete!
 >>> [CLI] bundle plan
 Plan: 0 to add, 0 to change, 0 to delete, 1 unchanged
 
->>> [CLI] bundle plan -o json
+>>> [CLI] bundle debug plan
 {
   "plan": {}
 }
@@ -71,7 +71,7 @@ update jobs.foo
 
 Plan: 0 to add, 1 to change, 0 to delete, 0 unchanged
 
->>> [CLI] bundle plan -o json
+>>> [CLI] bundle debug plan
 {
   "plan": {
     "resources.jobs.foo": {
@@ -89,7 +89,7 @@ Deployment complete!
 >>> [CLI] bundle plan
 Plan: 0 to add, 0 to change, 0 to delete, 1 unchanged
 
->>> [CLI] bundle plan -o json
+>>> [CLI] bundle debug plan
 {
   "plan": {}
 }
diff --git a/acceptance/bundle/resources/jobs/update/script b/acceptance/bundle/resources/jobs/update/script
@@ -1,9 +1,9 @@
 echo "*" > .gitignore
 trace $CLI bundle plan
-trace $CLI bundle plan -o json
+trace $CLI bundle debug plan
 trace $CLI bundle deploy
 trace $CLI bundle plan
-trace $CLI bundle plan -o json
+trace $CLI bundle debug plan
 
 print_requests() {
     jq --sort-keys 'select(.method != "GET" and (.path | contains("/jobs")))' < out.requests.txt
@@ -16,10 +16,10 @@ trace print_requests
 title "Update trigger.periodic.unit and re-deploy"
 trace update_file.py databricks.yml DAYS HOURS
 trace $CLI bundle plan
-trace $CLI bundle plan -o json
+trace $CLI bundle debug plan
 trace $CLI bundle deploy
 trace $CLI bundle plan
-trace $CLI bundle plan -o json
+trace $CLI bundle debug plan
 trace print_requests
 
 title "Fetch job ID and verify remote state"
diff --git a/acceptance/bundle/resources/pipelines/recreate/_script b/acceptance/bundle/resources/pipelines/recreate/_script
@@ -2,7 +2,7 @@ trace cat databricks.yml
 touch foo.py
 touch bar.py
 trace $CLI bundle plan  # should show 'create'
-trace $CLI bundle plan -o json
+trace $CLI bundle debug plan
 trace $CLI bundle deploy
 
 ppid1=`read_id.py pipelines my`
@@ -17,7 +17,7 @@ trace print_requests
 
 trace update_file.py databricks.yml $CONFIG_UPDATE
 trace $CLI bundle plan  # should show 'recreate'
-trace $CLI bundle plan -o json
+trace $CLI bundle debug plan
 trace $CLI bundle deploy --auto-approve
 trace print_requests
 
diff --git a/acceptance/bundle/resources/pipelines/recreate/change-catalog/output.txt b/acceptance/bundle/resources/pipelines/recreate/change-catalog/output.txt
@@ -19,7 +19,7 @@ create pipelines.my
 
 Plan: 1 to add, 0 to change, 0 to delete, 0 unchanged
 
->>> [CLI] bundle plan -o json
+>>> [CLI] bundle debug plan
 {
   "plan": {
     "resources.pipelines.my": {
@@ -64,7 +64,7 @@ recreate pipelines.my
 
 Plan: 1 to add, 0 to change, 1 to delete, 0 unchanged
 
->>> [CLI] bundle plan -o json
+>>> [CLI] bundle debug plan
 {
   "plan": {
     "resources.pipelines.my": {
diff --git a/acceptance/bundle/resources/pipelines/recreate/change-ingestion-definition/output.txt b/acceptance/bundle/resources/pipelines/recreate/change-ingestion-definition/output.txt
@@ -19,7 +19,7 @@ create pipelines.my
 
 Plan: 1 to add, 0 to change, 0 to delete, 0 unchanged
 
->>> [CLI] bundle plan -o json
+>>> [CLI] bundle debug plan
 {
   "plan": {
     "resources.pipelines.my": {
@@ -69,7 +69,7 @@ recreate pipelines.my
 
 Plan: 1 to add, 0 to change, 1 to delete, 0 unchanged
 
->>> [CLI] bundle plan -o json
+>>> [CLI] bundle debug plan
 {
   "plan": {
     "resources.pipelines.my": {
diff --git a/acceptance/bundle/resources/pipelines/recreate/change-storage/output.txt b/acceptance/bundle/resources/pipelines/recreate/change-storage/output.txt
@@ -19,7 +19,7 @@ create pipelines.my
 
 Plan: 1 to add, 0 to change, 0 to delete, 0 unchanged
 
->>> [CLI] bundle plan -o json
+>>> [CLI] bundle debug plan
 {
   "plan": {
     "resources.pipelines.my": {
@@ -64,7 +64,7 @@ recreate pipelines.my
 
 Plan: 1 to add, 0 to change, 1 to delete, 0 unchanged
 
->>> [CLI] bundle plan -o json
+>>> [CLI] bundle debug plan
 {
   "plan": {
     "resources.pipelines.my": {
diff --git a/acceptance/bundle/resources/volumes/change-name/output.txt b/acceptance/bundle/resources/volumes/change-name/output.txt
@@ -41,7 +41,7 @@ update volumes.volume1
 
 Plan: 0 to add, 1 to change, 0 to delete, 0 unchanged
 
->>> [CLI] bundle plan -o json
+>>> [CLI] bundle debug plan
 
 >>> [CLI] bundle deploy
 Uploading bundle files to /Workspace/Users/[USERNAME]/.bundle/test-bundle/default/files...
diff --git a/acceptance/bundle/resources/volumes/change-name/script b/acceptance/bundle/resources/volumes/change-name/script
@@ -15,7 +15,7 @@ trace update_file.py databricks.yml myvolume mynewvolume
 
 trace $CLI bundle plan
 # terraform marks this as "update", direct marks this as "update_with_id"
-trace $CLI bundle plan -o json > out.plan.$DATABRICKS_BUNDLE_ENGINE.txt
+trace $CLI bundle debug plan > out.plan.$DATABRICKS_BUNDLE_ENGINE.txt
 trace $CLI bundle deploy
 trace print_requests
 
diff --git a/cmd/bundle/debug.go b/cmd/bundle/debug.go
@@ -15,5 +15,6 @@ func newDebugCommand() *cobra.Command {
 	}
 	cmd.AddCommand(debug.NewTerraformCommand())
 	cmd.AddCommand(debug.NewRefSchemaCommand())
+	cmd.AddCommand(debug.NewPlanCommand())
 	return cmd
 }
diff --git a/cmd/bundle/debug/plan.go b/cmd/bundle/debug/plan.go
@@ -0,0 +1,44 @@
+package debug
+
+import (
+	"encoding/json"
+	"fmt"
+
+	"github.com/databricks/cli/cmd/bundle/utils"
+	"github.com/databricks/cli/cmd/root"
+	"github.com/databricks/cli/libs/logdiag"
+	"github.com/spf13/cobra"
+)
+
+func NewPlanCommand() *cobra.Command {
+	return &cobra.Command{
+		Use:   "plan",
+		Short: "Show deployment plan in JSON format (experimental)",
+		Long:  "Show the deployment plan for the current bundle configuration. This command is experimental and may change without notice.",
+		Args:  root.NoArgs,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			ctx := logdiag.InitContext(cmd.Context())
+			cmd.SetContext(ctx)
+			b := utils.ConfigureBundleWithVariables(cmd)
+			if b == nil || logdiag.HasError(ctx) {
+				return root.ErrAlreadyPrinted
+			}
+			plan, err := utils.GetPlan(ctx, b)
+			if err != nil {
+				return err
+			}
+
+			out := cmd.OutOrStdout()
+
+			buf, err := json.MarshalIndent(plan, "", "  ")
+			if err != nil {
+				return err
+			}
+			fmt.Fprintln(out, string(buf))
+			if logdiag.HasError(ctx) {
+				return root.ErrAlreadyPrinted
+			}
+			return nil
+		},
+	}
+}
diff --git a/cmd/bundle/plan.go b/cmd/bundle/plan.go
@@ -3,13 +3,12 @@ package bundle
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"strings"
 
 	"github.com/databricks/cli/bundle"
-	"github.com/databricks/cli/bundle/config/validate"
 	"github.com/databricks/cli/bundle/deployplan"
-	"github.com/databricks/cli/bundle/phases"
 	"github.com/databricks/cli/cmd/bundle/utils"
 	"github.com/databricks/cli/cmd/root"
 	"github.com/databricks/cli/libs/flags"
@@ -21,12 +20,11 @@ func newPlanCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "plan",
 		Short: "Show deployment plan",
-		Args:  root.NoArgs,
+		Long: `Show the deployment plan for the current bundle configuration.
 
-		// Output format may change without notice; main use case is in acceptance tests.
-		// Today, this command also uploads libraries, which is not the intent here. We need to refactor
-		// libraries.Upload() mutator to separate config mutation with actual upload.
-		Hidden: true,
+This command builds the bundle and displays the actions which will be done on resources that would be deployed, without making any changes.
+It is useful for previewing changes before running 'bundle deploy'.`,
+		Args: root.NoArgs,
 	}
 
 	var force bool
@@ -36,6 +34,13 @@ func newPlanCommand() *cobra.Command {
 	cmd.Flags().StringVarP(&clusterId, "cluster-id", "c", "", "Override cluster in the deployment with the given cluster ID.")
 	cmd.Flags().MarkDeprecated("compute-id", "use --cluster-id instead")
 
+	cmd.PreRunE = func(cmd *cobra.Command, args []string) error {
+		if f := cmd.Flag("output"); f != nil && f.Changed {
+			return errors.New("the -o/--output flag is not supported for this command. Use an experimental 'databricks bundle debug plan' command instead")
+		}
+		return nil
+	}
+
 	cmd.RunE = func(cmd *cobra.Command, args []string) error {
 		ctx := logdiag.InitContext(cmd.Context())
 		cmd.SetContext(ctx)
@@ -57,27 +62,9 @@ func newPlanCommand() *cobra.Command {
 			}
 		})
 
-		phases.Initialize(ctx, b)
-
-		if logdiag.HasError(ctx) {
-			return root.ErrAlreadyPrinted
-		}
-
-		bundle.ApplyContext(ctx, b, validate.FastValidate())
-
-		if logdiag.HasError(ctx) {
-			return root.ErrAlreadyPrinted
-		}
-
-		phases.Build(ctx, b)
-
-		if logdiag.HasError(ctx) {
-			return root.ErrAlreadyPrinted
-		}
-
-		plan := phases.Plan(ctx, b)
-		if logdiag.HasError(ctx) {
-			return root.ErrAlreadyPrinted
+		plan, err := utils.GetPlan(ctx, b)
+		if err != nil {
+			return err
 		}
 
 		// Count actions by type and collect formatted actions
diff --git a/cmd/bundle/utils/utils.go b/cmd/bundle/utils/utils.go
@@ -4,6 +4,9 @@ import (
 	"context"
 
 	"github.com/databricks/cli/bundle"
+	"github.com/databricks/cli/bundle/config/validate"
+	"github.com/databricks/cli/bundle/deployplan"
+	"github.com/databricks/cli/bundle/phases"
 	"github.com/databricks/cli/cmd/root"
 	"github.com/databricks/cli/libs/diag"
 	"github.com/databricks/cli/libs/logdiag"
@@ -38,3 +41,27 @@ func ConfigureBundleWithVariables(cmd *cobra.Command) *bundle.Bundle {
 
 	return b
 }
+
+func GetPlan(ctx context.Context, b *bundle.Bundle) (*deployplan.Plan, error) {
+	phases.Initialize(ctx, b)
+	if logdiag.HasError(ctx) {
+		return nil, root.ErrAlreadyPrinted
+	}
+
+	bundle.ApplyContext(ctx, b, validate.FastValidate())
+	if logdiag.HasError(ctx) {
+		return nil, root.ErrAlreadyPrinted
+	}
+
+	phases.Build(ctx, b)
+	if logdiag.HasError(ctx) {
+		return nil, root.ErrAlreadyPrinted
+	}
+
+	plan := phases.Plan(ctx, b)
+	if logdiag.HasError(ctx) {
+		return nil, root.ErrAlreadyPrinted
+	}
+
+	return plan, nil
+}

Original file line number	Diff line number	Diff line change
`@@ -4,7 +4,7 @@ create jobs.foo`
`4`	`4`
`5`	`5`	`Plan: 1 to add, 0 to change, 0 to delete, 0 unchanged`
`6`	`6`
`7`		`->>> [CLI] bundle plan -o json`
	`7`	`+>>> [CLI] bundle debug plan`
`8`	`8`	`{`
`9`	`9`	`"plan": {`
`10`	`10`	`"resources.jobs.foo": {`
`@@ -22,7 +22,7 @@ Deployment complete!`
`22`	`22`	`>>> [CLI] bundle plan`
`23`	`23`	`Plan: 0 to add, 0 to change, 0 to delete, 1 unchanged`
`24`	`24`
`25`		`->>> [CLI] bundle plan -o json`
	`25`	`+>>> [CLI] bundle debug plan`
`26`	`26`	`{`
`27`	`27`	`"plan": {}`
`28`	`28`	`}`
`@@ -71,7 +71,7 @@ update jobs.foo`
`71`	`71`
`72`	`72`	`Plan: 0 to add, 1 to change, 0 to delete, 0 unchanged`
`73`	`73`
`74`		`->>> [CLI] bundle plan -o json`
	`74`	`+>>> [CLI] bundle debug plan`
`75`	`75`	`{`
`76`	`76`	`"plan": {`
`77`	`77`	`"resources.jobs.foo": {`
`@@ -89,7 +89,7 @@ Deployment complete!`
`89`	`89`	`>>> [CLI] bundle plan`
`90`	`90`	`Plan: 0 to add, 0 to change, 0 to delete, 1 unchanged`
`91`	`91`
`92`		`->>> [CLI] bundle plan -o json`
	`92`	`+>>> [CLI] bundle debug plan`
`93`	`93`	`{`
`94`	`94`	`"plan": {}`
`95`	`95`	`}`
Original file line number	Diff line number	Diff line change
`@@ -19,7 +19,7 @@ create pipelines.my`
`19`	`19`
`20`	`20`	`Plan: 1 to add, 0 to change, 0 to delete, 0 unchanged`
`21`	`21`
`22`		`->>> [CLI] bundle plan -o json`
	`22`	`+>>> [CLI] bundle debug plan`
`23`	`23`	`{`
`24`	`24`	`"plan": {`
`25`	`25`	`"resources.pipelines.my": {`
`@@ -64,7 +64,7 @@ recreate pipelines.my`
`64`	`64`
`65`	`65`	`Plan: 1 to add, 0 to change, 1 to delete, 0 unchanged`
`66`	`66`
`67`		`->>> [CLI] bundle plan -o json`
	`67`	`+>>> [CLI] bundle debug plan`
`68`	`68`	`{`
`69`	`69`	`"plan": {`
`70`	`70`	`"resources.pipelines.my": {`