Add completion install, uninstall, and status subcommands (#4581)

## Why

Users currently have to manually configure shell tab completion by
piping `databricks completion <shell>` output into the right RC file.
This is error-prone and shell-specific. Adding
`install`/`uninstall`/`status` subcommands automates the setup.

## Changes

Adds three new subcommands to the existing `completion` command:

```
databricks completion
  databricks completion bash          # Generate bash completion script
  databricks completion zsh           # Generate zsh completion script
  databricks completion fish          # Generate fish completion script
  databricks completion powershell    # Generate powershell completion script
  databricks completion install       # NEW: Install completions into shell RC file
  databricks completion uninstall     # NEW: Remove completions from shell RC file
  databricks completion status        # NEW: Show current completion status
```

**`completion install [--shell <shell>] [--auto-approve]`** —
Auto-detects shell from `$SHELL`, appends an eval shim wrapped in
`BEGIN`/`END` markers to the appropriate RC file. Fish uses a file drop
to `~/.config/fish/completions/` instead. Shows the detected shell and
target file and asks for confirmation before writing; `--auto-approve`
skips the prompt (for scripts/agents). If completions are already
present (our marker, Homebrew, or an external fish file), reports that
and exits without prompting.

**`completion uninstall [--shell <shell>] [--auto-approve]`** — Removes
the marker block from the RC file (or deletes the fish completions file
if it contains our marker). Strict parsing: returns an error if markers
are corrupted rather than risking RC file damage. External completions
(Homebrew, package manager fish files) are detected and reported but not
removed.

**`completion status [--shell <shell>]`** — Reports whether completions
are installed, detecting our marker block, Homebrew-based zsh installs,
and fish file-based installs. Also serves as a dry-run to preview the
detected shell and target file before running install.

**Shell support**: bash, zsh, fish, powershell (pwsh 7+), powershell5
(Windows PowerShell 5.1). Shell detection checks `$SHELL` first (catches
Git Bash/MSYS on Windows), falls back to PATH lookup on Windows. If
`$SHELL` contains an unrecognized value on Windows (e.g.
`powershell.exe`), detection falls through to PATH-based lookup.

**Architecture**: Core logic lives in `libs/completion/` with no cobra
dependency, so it can be called from other commands (e.g. a guided setup
flow). `cmd/completion/` contains thin cobra wrappers. The existing
shell generation subcommands (bash/zsh/fish/powershell) are
reimplemented with runtime writer resolution to avoid a Cobra
`OutOrStdout()` capture timing issue with the test harness.

## Tests

- Unit tests in `libs/completion/` covering shell detection,
install/uninstall/status logic, idempotency, marker corruption
detection, edge cases (empty files, missing dirs, permission
preservation, Windows permission semantics, fish foreign-file ownership,
`$SHELL=powershell.exe` fallback)
- Acceptance test in `acceptance/cmd/completion/` covering the full
install → status → idempotent reinstall → uninstall → status round-trip,
plus smoke tests for all four shell script generators and
`--no-descriptions`

---------

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: simonfaltum

NEXT_CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Release v0.290.0
 
+### CLI
+* Add `completion install`, `uninstall`, and `status` subcommands ([#4581](https://github.com/databricks/cli/pull/4581))
+
+### Internal
+
 ### Dependency updates
 * Upgrade TF provider to 1.109.0 ([#4561](https://github.com/databricks/cli/pull/4561))
 * Upgrade Go SDK to v0.110.0 ([#4552](https://github.com/databricks/cli/pull/4552))

acceptance/cmd/completion/out.test.toml

@@ -0,0 +1,37 @@
+
+>>> [CLI] completion install --shell zsh --auto-approve
+Databricks CLI completions installed for zsh.
+Restart your shell or run 'source home/.zshrc' to activate.
+
+Warning: zsh completions require the completion system to be initialized.
+Add the following to your home/.zshrc:
+  autoload -U compinit && compinit
+
+>>> [CLI] completion status --shell zsh
+Shell:   zsh
+File:    home/.zshrc
+Status:  installed
+
+Warning: zsh completions require the completion system to be initialized.
+Add the following to your home/.zshrc:
+  autoload -U compinit && compinit
+
+>>> [CLI] completion install --shell zsh --auto-approve
+Databricks CLI completions are already installed for zsh in home/.zshrc.
+
+Warning: zsh completions require the completion system to be initialized.
+Add the following to your home/.zshrc:
+  autoload -U compinit && compinit
+
+>>> [CLI] completion uninstall --shell zsh --auto-approve
+Databricks CLI completions removed for zsh from home/.zshrc.
+
+>>> [CLI] completion status --shell zsh
+Shell:   zsh
+File:    home/.zshrc
+Status:  not installed
+# bash completion V2 for databricks                           -*- shell-script -*-
+#compdef databricks
+# fish completion for databricks                           -*- shell-script -*-
+# powershell completion for databricks                           -*- shell-script -*-
+# bash completion V2 for databricks                           -*- shell-script -*-

acceptance/cmd/completion/output.txt

@@ -0,0 +1,31 @@
+sethome "./home"
+
+# Track the home path for stable output across platforms.
+add_repl.py "$HOME" HOME
+
+# Prevent Homebrew detection from affecting status output.
+export HOMEBREW_PREFIX=/nonexistent
+
+# Test install (use zsh to avoid OS-dependent bash RC file path)
+trace $CLI completion install --shell zsh --auto-approve
+
+# Test status shows installed
+trace $CLI completion status --shell zsh
+
+# Test idempotent install (--auto-approve is harmless when already installed)
+trace $CLI completion install --shell zsh --auto-approve
+
+# Test uninstall
+trace $CLI completion uninstall --shell zsh --auto-approve
+
+# Test status after uninstall
+trace $CLI completion status --shell zsh
+
+# Test shell subcommands produce output
+$CLI completion bash 2>&1 | head -1
+$CLI completion zsh 2>&1 | head -1
+$CLI completion fish 2>&1 | head -1
+$CLI completion powershell 2>&1 | head -1
+
+# Test bash --no-descriptions
+$CLI completion bash --no-descriptions 2>&1 | head -1

acceptance/cmd/completion/script

@@ -0,0 +1,10 @@
+Ignore = [
+    "home",
+]
+
+Local = true
+Cloud = false
+
+# Completion tests don't involve bundles, skip the engine matrix.
+[EnvMatrix]
+DATABRICKS_BUNDLE_ENGINE = ["terraform"]

acceptance/cmd/completion/test.toml

@@ -12,6 +12,7 @@ import (
 	"github.com/databricks/cli/cmd/auth"
 	"github.com/databricks/cli/cmd/bundle"
 	"github.com/databricks/cli/cmd/cache"
+	"github.com/databricks/cli/cmd/completion"
 	"github.com/databricks/cli/cmd/configure"
 	"github.com/databricks/cli/cmd/experimental"
 	"github.com/databricks/cli/cmd/fs"
@@ -94,6 +95,7 @@ func New(ctx context.Context) *cobra.Command {
 	// Add other subcommands.
 	cli.AddCommand(api.New())
 	cli.AddCommand(auth.New())
+	cli.AddCommand(completion.New())
 	cli.AddCommand(bundle.New())
 	cli.AddCommand(cache.New())
 	cli.AddCommand(experimental.New())

cmd/cmd.go

@@ -0,0 +1,204 @@
+package completion
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/databricks/cli/cmd/root"
+	"github.com/databricks/cli/libs/cmdio"
+	libcompletion "github.com/databricks/cli/libs/completion"
+	"github.com/spf13/cobra"
+)
+
+// New returns the "completion" command with shell subcommands and
+// install/uninstall/status subcommands. Providing a command named
+// "completion" prevents Cobra's InitDefaultCompletionCmd from generating
+// its default, so we replicate the shell subcommands here with runtime
+// writer resolution to avoid the frozen-writer bug.
+func New() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "completion",
+		Short: "Generate the autocompletion script for the specified shell",
+		Long: `Generate the autocompletion script for databricks for the specified shell.
+See each sub-command's help for details on how to use the generated script.
+`,
+		Args:              cobra.NoArgs,
+		ValidArgsFunction: cobra.NoFileCompletions,
+		RunE:              root.ReportUnknownSubcommand,
+	}
+
+	cmd.AddCommand(
+		newBashCmd(),
+		newZshCmd(),
+		newFishCmd(),
+		newPowershellCmd(),
+		newInstallCmd(),
+		newUninstallCmd(),
+		newStatusCmd(),
+	)
+
+	return cmd
+}
+
+func newBashCmd() *cobra.Command {
+	var noDesc bool
+	cmd := &cobra.Command{
+		Use:   "bash",
+		Short: "Generate the autocompletion script for bash",
+		Long: `Generate the autocompletion script for the bash shell.
+
+This script depends on the 'bash-completion' package.
+If it is not installed already, you can install it via your OS's package manager.
+
+To load completions in your current shell session:
+
+	source <(databricks completion bash)
+
+To load completions for every new session, execute once:
+
+#### Linux:
+
+	databricks completion bash > /etc/bash_completion.d/databricks
+
+#### macOS:
+
+	databricks completion bash > $(brew --prefix)/etc/bash_completion.d/databricks
+
+You will need to start a new shell for this setup to take effect.
+`,
+		Args:                  cobra.NoArgs,
+		DisableFlagsInUseLine: true,
+		ValidArgsFunction:     cobra.NoFileCompletions,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return cmd.Root().GenBashCompletionV2(cmd.OutOrStdout(), !noDesc)
+		},
+	}
+	cmd.Flags().BoolVar(&noDesc, "no-descriptions", false, "disable completion descriptions")
+	return cmd
+}
+
+func newZshCmd() *cobra.Command {
+	var noDesc bool
+	cmd := &cobra.Command{
+		Use:   "zsh",
+		Short: "Generate the autocompletion script for zsh",
+		Long: `Generate the autocompletion script for the zsh shell.
+
+If shell completion is not already enabled in your environment you will need
+to enable it.  You can execute the following once:
+
+	echo "autoload -U compinit; compinit" >> ~/.zshrc
+
+To load completions in your current shell session:
+
+	source <(databricks completion zsh)
+
+To load completions for every new session, execute once:
+
+#### Linux:
+
+	databricks completion zsh > "${fpath[1]}/_databricks"
+
+#### macOS:
+
+	databricks completion zsh > $(brew --prefix)/share/zsh/site-functions/_databricks
+
+You will need to start a new shell for this setup to take effect.
+`,
+		Args:              cobra.NoArgs,
+		ValidArgsFunction: cobra.NoFileCompletions,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if noDesc {
+				return cmd.Root().GenZshCompletionNoDesc(cmd.OutOrStdout())
+			}
+			return cmd.Root().GenZshCompletion(cmd.OutOrStdout())
+		},
+	}
+	cmd.Flags().BoolVar(&noDesc, "no-descriptions", false, "disable completion descriptions")
+	return cmd
+}
+
+func newFishCmd() *cobra.Command {
+	var noDesc bool
+	cmd := &cobra.Command{
+		Use:   "fish",
+		Short: "Generate the autocompletion script for fish",
+		Long: `Generate the autocompletion script for the fish shell.
+
+To load completions in your current shell session:
+
+	databricks completion fish | source
+
+To load completions for every new session, execute once:
+
+	databricks completion fish > ~/.config/fish/completions/databricks.fish
+
+You will need to start a new shell for this setup to take effect.
+`,
+		Args:              cobra.NoArgs,
+		ValidArgsFunction: cobra.NoFileCompletions,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return cmd.Root().GenFishCompletion(cmd.OutOrStdout(), !noDesc)
+		},
+	}
+	cmd.Flags().BoolVar(&noDesc, "no-descriptions", false, "disable completion descriptions")
+	return cmd
+}
+
+func newPowershellCmd() *cobra.Command {
+	var noDesc bool
+	cmd := &cobra.Command{
+		Use:   "powershell",
+		Short: "Generate the autocompletion script for powershell",
+		Long: `Generate the autocompletion script for powershell.
+
+To load completions in your current shell session:
+
+	databricks completion powershell | Out-String | Invoke-Expression
+
+To load completions for every new session, add the output of the above command
+to your powershell profile.
+`,
+		Args:              cobra.NoArgs,
+		ValidArgsFunction: cobra.NoFileCompletions,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if noDesc {
+				return cmd.Root().GenPowerShellCompletion(cmd.OutOrStdout())
+			}
+			return cmd.Root().GenPowerShellCompletionWithDesc(cmd.OutOrStdout())
+		},
+	}
+	cmd.Flags().BoolVar(&noDesc, "no-descriptions", false, "disable completion descriptions")
+	return cmd
+}
+
+// warnIfCompinitMissing prints a warning when zsh completions are present but
+// the user's .zshrc does not call compinit. Without compinit, neither our eval
+// shim nor Homebrew's _databricks file will be loaded.
+func warnIfCompinitMissing(ctx context.Context, shell libcompletion.Shell, home string) {
+	if shell != libcompletion.Zsh {
+		return
+	}
+	rcPath := libcompletion.TargetFilePath(shell, home)
+	content, err := os.ReadFile(rcPath)
+	if err != nil {
+		return
+	}
+	if strings.Contains(string(content), "compinit") {
+		return
+	}
+	cmdio.LogString(ctx, "")
+	cmdio.LogString(ctx, "Warning: zsh completions require the completion system to be initialized.")
+	cmdio.LogString(ctx, "Add the following to your "+filepath.ToSlash(rcPath)+":")
+	cmdio.LogString(ctx, "  autoload -U compinit && compinit")
+}
+
+// addShellFlag registers the --shell flag and its completion function on cmd.
+func addShellFlag(cmd *cobra.Command, target *string) {
+	cmd.Flags().StringVar(target, "shell", "", "Shell type: bash, zsh, fish, powershell, powershell5")
+	cmd.RegisterFlagCompletionFunc("shell", func(cmd *cobra.Command, args []string, toComplete string) ([]cobra.Completion, cobra.ShellCompDirective) {
+		return []cobra.Completion{"bash", "zsh", "fish", "powershell", "powershell5"}, cobra.ShellCompDirectiveNoFileComp
+	})
+}