Improve shell completions for buf flags (#4416)

This takes a pass at improving the shell completions provided by `buf`
by wiring into cobra's completion system.

This:

* Adds completions for "enum" based flags (provides the potential
  values; disables flags & generally orders from most-used to least-used)
* Adds directory-only completions for `--output` in generate and export
* Adds file-extension completions for `--template` (yaml extensions) and
  `--binary` (wasm)
* Disables file completions for free-form string flags like `--label`,
  `--source-control-url`, `--header`, etc. where it's unlikely that
  a user would want to supply a local file name

Implementation-wise, this is all wired up under ModifyCobra, so we need
the latest version of app-go which fixes that working on subcommands. It
generally uses `errors.Join` just to simplify the error cases, which
should not occur. Shared completions are in
`private/buf/bufcli/completions.go`.

Vaguely related to #4402, which is aiming to add more dynamic
completions. In that PR, I mentioned further improvements to completions
for more dynamic situations, but this should shore up the "base case" of
the relatively straightforward static-ish completions.

Ref: https://cobra.dev/docs/how-to-guides/shell-completion/

Author: stefanvanburen

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## [Unreleased]
 
+- Improve shell completions for `buf` flags with fixed value sets and file/directory arguments.
 - Add support for Edition 2024 syntax to `buf format`.
 
 ## [v1.67.0] - 2026-04-01

cmd/buf/buf.go

@@ -462,7 +462,14 @@ func newRootCommand(name string) *appcmd.Command {
 		},
 		ModifyCobra: func(cobraCommand *cobra.Command) error {
 			cobraCommand.AddCommand(bufcobra.NewWebpagesCommand("webpages", cobraCommand))
-			return nil
+			return cobraCommand.RegisterFlagCompletionFunc(
+				"log-format",
+				cobra.FixedCompletions([]string{
+					appext.LogFormatText.String(),
+					appext.LogFormatColor.String(),
+					appext.LogFormatJSON.String(),
+				}, cobra.ShellCompDirectiveNoFileComp|cobra.ShellCompDirectiveKeepOrder),
+			)
 		},
 	}
 }

cmd/buf/internal/command/alpha/registry/token/tokenget/tokenget.go

@@ -28,6 +28,7 @@ import (
 	"github.com/bufbuild/buf/private/pkg/connectclient"
 	"github.com/bufbuild/buf/private/pkg/netext"
 	"github.com/bufbuild/buf/private/pkg/syserror"
+	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
 )
 
@@ -52,6 +53,9 @@ func NewCommand(
 			},
 		),
 		BindFlags: flags.Bind,
+		ModifyCobra: func(cmd *cobra.Command) error {
+			return bufcli.RegisterFlagCompletionOutputFormat(cmd, formatFlagName)
+		},
 	}
 }
 

cmd/buf/internal/command/alpha/registry/token/tokenlist/tokenlist.go

@@ -28,6 +28,7 @@ import (
 	"github.com/bufbuild/buf/private/pkg/connectclient"
 	"github.com/bufbuild/buf/private/pkg/netext"
 	"github.com/bufbuild/buf/private/pkg/syserror"
+	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
 )
 
@@ -54,6 +55,9 @@ func NewCommand(
 			},
 		),
 		BindFlags: flags.Bind,
+		ModifyCobra: func(cmd *cobra.Command) error {
+			return bufcli.RegisterFlagCompletionOutputFormat(cmd, formatFlagName)
+		},
 	}
 }
 

cmd/buf/internal/command/beta/registry/plugin/pluginpush/pluginpush.go

@@ -47,6 +47,7 @@ import (
 	pkgv1 "github.com/google/go-containerregistry/pkg/v1"
 	"github.com/google/go-containerregistry/pkg/v1/remote"
 	"github.com/google/go-containerregistry/pkg/v1/remote/transport"
+	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
 )
 
@@ -83,6 +84,12 @@ func NewCommand(
 			},
 		),
 		BindFlags: flags.Bind,
+		ModifyCobra: func(cmd *cobra.Command) error {
+			return errors.Join(
+				bufcli.RegisterFlagCompletionOutputFormat(cmd, formatFlagName),
+				bufcli.RegisterFlagCompletionVisibility(cmd, visibilityFlagName),
+			)
+		},
 	}
 }
 

cmd/buf/internal/command/breaking/breaking.go

@@ -38,6 +38,7 @@ import (
 	"github.com/bufbuild/buf/private/bufpkg/bufregistryapi/bufregistryapimodule"
 	"github.com/bufbuild/buf/private/pkg/syserror"
 	"github.com/bufbuild/buf/private/pkg/wasm"
+	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
 )
 
@@ -74,6 +75,9 @@ func NewCommand(
 			},
 		),
 		BindFlags: flags.Bind,
+		ModifyCobra: func(cmd *cobra.Command) error {
+			return bufcli.RegisterFlagCompletionErrorFormat(cmd, errorFormatFlagName)
+		},
 	}
 }
 

cmd/buf/internal/command/build/build.go

@@ -27,6 +27,7 @@ import (
 	"github.com/bufbuild/buf/private/buf/buffetch"
 	"github.com/bufbuild/buf/private/bufpkg/bufanalysis"
 	"github.com/bufbuild/buf/private/bufpkg/bufimage/bufimageutil"
+	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
 )
 
@@ -62,6 +63,9 @@ func NewCommand(
 			},
 		),
 		BindFlags: flags.Bind,
+		ModifyCobra: func(cmd *cobra.Command) error {
+			return bufcli.RegisterFlagCompletionErrorFormat(cmd, errorFormatFlagName)
+		},
 	}
 }
 

cmd/buf/internal/command/config/configlsmodules/configlsmodules.go

@@ -31,6 +31,7 @@ import (
 	"github.com/bufbuild/buf/private/bufpkg/bufconfig"
 	"github.com/bufbuild/buf/private/pkg/normalpath"
 	"github.com/bufbuild/buf/private/pkg/syserror"
+	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
 )
 
@@ -69,6 +70,16 @@ func NewCommand(
 			},
 		),
 		BindFlags: flags.Bind,
+		ModifyCobra: func(cmd *cobra.Command) error {
+			return cmd.RegisterFlagCompletionFunc(
+				formatFlagName,
+				cobra.FixedCompletions([]string{
+					formatPath,
+					formatName,
+					formatJSON,
+				}, cobra.ShellCompDirectiveNoFileComp|cobra.ShellCompDirectiveKeepOrder),
+			)
+		},
 	}
 }
 

cmd/buf/internal/command/config/internal/internal.go

@@ -31,6 +31,7 @@ import (
 	"github.com/bufbuild/buf/private/bufpkg/bufconfig"
 	"github.com/bufbuild/buf/private/pkg/normalpath"
 	"github.com/bufbuild/buf/private/pkg/syserror"
+	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
 )
 
@@ -66,6 +67,12 @@ func NewLSCommand(
 			},
 		),
 		BindFlags: flags.Bind,
+		ModifyCobra: func(cmd *cobra.Command) error {
+			return errors.Join(
+				bufcli.RegisterFlagCompletionRuleFormat(cmd, formatFlagName),
+				bufcli.RegisterFlagCompletionFileVersion(cmd, versionFlagName),
+			)
+		},
 	}
 }
 
@@ -123,11 +130,13 @@ func (f *flags) Bind(flagSet *pflag.FlagSet) {
 		fmt.Sprintf(
 			"List all the rules for the given configuration version. By default, the version in the buf.yaml in the current directory is used, or the latest version otherwise (currently v2). Cannot be set if --%s is set. Must be one of %s",
 			configuredOnlyFlagName,
-			xslices.Map(
-				bufconfig.AllFileVersions,
-				func(fileVersion bufconfig.FileVersion) string {
-					return fileVersion.String()
-				},
+			xstrings.SliceToString(
+				xslices.Map(
+					bufconfig.AllFileVersions,
+					func(fileVersion bufconfig.FileVersion) string {
+						return fileVersion.String()
+					},
+				),
 			),
 		),
 	)

cmd/buf/internal/command/convert/convert.go

@@ -32,6 +32,7 @@ import (
 	"github.com/bufbuild/buf/private/bufpkg/bufimage/bufimageutil"
 	"github.com/bufbuild/buf/private/bufpkg/bufmodule"
 	"github.com/bufbuild/buf/private/gen/data/datawkt"
+	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
 )
 
@@ -91,6 +92,9 @@ Use a module on the bsr:
 			},
 		),
 		BindFlags: flags.Bind,
+		ModifyCobra: func(cmd *cobra.Command) error {
+			return bufcli.RegisterFlagCompletionErrorFormat(cmd, errorFormatFlagName)
+		},
 	}
 }