Improve shell completions for buf flags

CHANGELOG.md

@@ -5,6 +5,7 @@
 - Add support for `--rbs_out` as a `protoc_builtin` plugin (requires protoc v34.0+).
 - Add relevant links from CEL LSP hover documentation to either <celbyexample.com> or <protovalidate.com>
 - Skip writing unchanged output files in `buf generate` to preserve modification times
+- Improve shell completions for `buf` flags with fixed value sets and file/directory arguments.
 
 ## [v1.66.1] - 2026-03-09
 

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)
+		},
 	}
 }
 

cmd/buf/internal/command/curl/curl.go

@@ -43,6 +43,7 @@ import (
 	"github.com/bufbuild/buf/private/pkg/verbose"
 	"github.com/quic-go/quic-go"
 	"github.com/quic-go/quic-go/http3"
+	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
 	"google.golang.org/protobuf/reflect/protoreflect"
 )
@@ -195,6 +196,24 @@ exit code that is the gRPC code, shifted three bits to the left.
 			},
 		),
 		BindFlags: flags.Bind,
+		ModifyCobra: func(cmd *cobra.Command) error {
+			return errors.Join(
+				cmd.RegisterFlagCompletionFunc(
+					protocolFlagName,
+					cobra.FixedCompletions([]string{
+						connect.ProtocolConnect,
+						connect.ProtocolGRPC,
+						connect.ProtocolGRPCWeb,
+					}, cobra.ShellCompDirectiveNoFileComp|cobra.ShellCompDirectiveKeepOrder),
+				),
+				cmd.RegisterFlagCompletionFunc(
+					reflectProtocolFlagName,
+					cobra.FixedCompletions(bufcurl.AllKnownReflectProtocolStrings, cobra.ShellCompDirectiveNoFileComp|cobra.ShellCompDirectiveKeepOrder),
+				),
+				cmd.RegisterFlagCompletionFunc(headerFlagName, cobra.NoFileCompletions),
+				cmd.RegisterFlagCompletionFunc(reflectHeaderFlagName, cobra.NoFileCompletions),
+			)
+		},
 	}
 }
 

cmd/buf/internal/command/dep/depgraph/depgraph.go

@@ -17,6 +17,7 @@ package depgraph
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"slices"
 
@@ -31,6 +32,7 @@ import (
 	"github.com/bufbuild/buf/private/pkg/dag"
 	"github.com/bufbuild/buf/private/pkg/uuidutil"
 	"github.com/google/uuid"
+	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
 )
 
@@ -90,6 +92,18 @@ buf dep graph | dot -Tpng >| graph.png && open graph.png
 			},
 		),
 		BindFlags: flags.Bind,
+		ModifyCobra: func(cmd *cobra.Command) error {
+			return errors.Join(
+				bufcli.RegisterFlagCompletionErrorFormat(cmd, errorFormatFlagName),
+				cmd.RegisterFlagCompletionFunc(
+					formatFlagName,
+					cobra.FixedCompletions([]string{
+						cobra.CompletionWithDesc(dotFormatString, "Graphviz DOT"),
+						jsonFormatString,
+					}, cobra.ShellCompDirectiveNoFileComp|cobra.ShellCompDirectiveKeepOrder),
+				),
+			)
+		},
 	}
 }
 

cmd/buf/internal/command/export/export.go

@@ -32,6 +32,7 @@ import (
 	"github.com/bufbuild/buf/private/pkg/storage"
 	"github.com/bufbuild/buf/private/pkg/storage/storageos"
 	"github.com/bufbuild/buf/private/pkg/syserror"
+	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
 )
 
@@ -86,6 +87,12 @@ Export a git repo to a local directory.
 			},
 		),
 		BindFlags: flags.Bind,
+		ModifyCobra: func(cmd *cobra.Command) error {
+			return cmd.RegisterFlagCompletionFunc(
+				outputFlagName,
+				cobra.FixedCompletions(nil, cobra.ShellCompDirectiveFilterDirs),
+			)
+		},
 	}
 }
 

cmd/buf/internal/command/format/format.go

@@ -35,6 +35,7 @@ import (
 	"github.com/bufbuild/buf/private/pkg/storage"
 	"github.com/bufbuild/buf/private/pkg/storage/storageos"
 	"github.com/bufbuild/buf/private/pkg/syserror"
+	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
 )
 
@@ -165,6 +166,9 @@ The -w and -o flags cannot be used together in a single invocation.
 			},
 		),
 		BindFlags: flags.Bind,
+		ModifyCobra: func(cmd *cobra.Command) error {
+			return bufcli.RegisterFlagCompletionErrorFormat(cmd, errorFormatFlagName)
+		},
 	}
 }
 

cmd/buf/internal/command/generate/generate.go

@@ -16,6 +16,7 @@ package generate
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"log/slog"
 	"os"
@@ -33,6 +34,7 @@ import (
 	"github.com/bufbuild/buf/private/bufpkg/bufconfig"
 	"github.com/bufbuild/buf/private/bufpkg/bufimage"
 	"github.com/bufbuild/buf/private/pkg/storage/storageos"
+	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
 )
 
@@ -384,6 +386,21 @@ Insertion points are processed in the order the plugins are specified in the tem
 			},
 		),
 		BindFlags: flags.Bind,
+		ModifyCobra: func(cmd *cobra.Command) error {
+			return errors.Join(
+				bufcli.RegisterFlagCompletionErrorFormat(cmd, errorFormatFlagName),
+				cmd.RegisterFlagCompletionFunc(
+					templateFlagName,
+					cobra.FixedCompletions([]string{"yaml", "yml", "json"}, cobra.ShellCompDirectiveFilterFileExt),
+				),
+				cmd.RegisterFlagCompletionFunc(
+					baseOutDirPathFlagName,
+					cobra.FixedCompletions(nil, cobra.ShellCompDirectiveFilterDirs),
+				),
+				cmd.RegisterFlagCompletionFunc(typeFlagName, cobra.NoFileCompletions),
+				cmd.RegisterFlagCompletionFunc(excludeTypeFlagName, cobra.NoFileCompletions),
+			)
+		},
 	}
 }
 

cmd/buf/internal/command/lint/lint.go

@@ -27,6 +27,7 @@ import (
 	"github.com/bufbuild/buf/private/bufpkg/bufanalysis"
 	"github.com/bufbuild/buf/private/bufpkg/bufcheck"
 	"github.com/bufbuild/buf/private/bufpkg/bufconfig"
+	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
 )
 
@@ -55,6 +56,9 @@ func NewCommand(
 			},
 		),
 		BindFlags: flags.Bind,
+		ModifyCobra: func(cmd *cobra.Command) error {
+			return bufcli.RegisterFlagCompletionLintErrorFormat(cmd, errorFormatFlagName)
+		},
 	}
 }
 

cmd/buf/internal/command/lsfiles/lsfiles.go

@@ -32,6 +32,7 @@ import (
 	"github.com/bufbuild/buf/private/gen/data/datawkt"
 	"github.com/bufbuild/buf/private/pkg/uuidutil"
 	"github.com/google/uuid"
+	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
 )
 
@@ -72,6 +73,16 @@ func NewCommand(
 			},
 		),
 		BindFlags: flags.Bind,
+		ModifyCobra: func(cmd *cobra.Command) error {
+			return cmd.RegisterFlagCompletionFunc(
+				formatFlagName,
+				cobra.FixedCompletions([]string{
+					formatText,
+					formatJSON,
+					formatImport,
+				}, cobra.ShellCompDirectiveNoFileComp|cobra.ShellCompDirectiveKeepOrder),
+			)
+		},
 	}
 }