grpctl

README

grpctl

A golang package for easily creating custom cli tools from FileDescriptors, or through the gRPC reflection API.

📖 Table of contents

• Reflection cli mode
• File descriptor mode
• Autocompletion
• Flags
• Design
• Contributing
• License

🪞 Reflection cli mode

To be used like grpcurl against reflection APIs but with tab completion.

📥 Install

go get github.com/joshcarp/grpctl/cmd/grpctl
grpctl --help

  -a, --address string       Address in form 'host:port'
      --config string        Config file (default is $HOME/.grpctl.yaml)
  -H, --header stringArray   Header in form 'key: value'
  -h, --help                 help for grpctl
  -p, --plaintext            Dial grpc.WithInsecure

🗄️ File descriptor mode

To easily create a cli tool for your grpc APIs using the code generated protoreflect.FileDescriptor To view all options that can be used, see opts.go.

📥 Install

func main() {
	cmd := &cobra.Command{
		Use:   "billingctl",
		Short: "an example cli tool for the gcp billing api",
	}
	err := grpctl.BuildCommand(cmd,
		grpctl.WithArgs(os.Args),
		grpctl.WithFileDescriptors(
			billing.File_google_cloud_billing_v1_cloud_billing_proto,
			billing.File_google_cloud_billing_v1_cloud_catalog_proto,
		),
	)
	if err != nil {
		log.Print(err)
	}
	if err := grpctl.RunCommand(cmd, context.Background()); err != nil {
		log.Print(err)
	}
}

🤖 Autocompletion

run grpctl completion --help and do what it says

🏳️‍🌈 Flags

• --address

grpctl --address=<scheme://host:port>

• it is important that the = is used with flags, otherwise the value will be interpreted as a command which does not exist.

• --header

grpctl --address=<scheme://host:port> -H="Foo:Bar" -H="Bar: Foo"

• Any white spaces at the start of the value will be stripped

• --protocol

grpctl --address=<scheme://host:port> --protocol=<connect|grpc|grpcweb>

• Specifies which rpc protocol to use, default=grpc

• --http1

grpctl --address=<scheme://host:port> --http1

• Use a http1.1 client instead of http2

🧠 Design

Design documents (more like a stream of consciousness) can be found in ./design.

🔧 Contributing

This project is still in an alpha state, any contributions are welcome see CONTRIBUTING.md.

There is also a slack channel on gophers slack: #grpctl

🖋️ License

See LICENSE for more details.

🎉 Acknowledgements

• @dancantos/@anzboi and I were talking about protoc-gen-cobra when dan came up with the idea of using the proto descriptors to generate cobra commands on the fly.

Documentation

Overview

Package grpctl provides to build cobra commands from proto descriptors.

Index

• func BuildCommand(cmd *cobra.Command, opts ...CommandOption) error
• func CommandFromFileDescriptor(cmd *cobra.Command, methods protoreflect.FileDescriptor) error
• func CommandFromFileDescriptors(cmd *cobra.Command, descriptors ...protoreflect.FileDescriptor) error
• func CommandFromMethodDescriptor(cmd *cobra.Command, method protoreflect.MethodDescriptor) error
• func CommandFromServiceDescriptor(cmd *cobra.Command, service protoreflect.ServiceDescriptor) error
• func ReflectionCommand() (*cobra.Command, error)
• func WithStdin(stdin io.Reader) func(cmd *cobra.Command) error
• type CommandOption
  • func WithArgs(args []string) CommandOption
  • func WithCompletion() CommandOption
  • func WithContextDescriptorFunc(...) CommandOption
  • func WithContextFunc(f func(context.Context, *cobra.Command) (context.Context, error)) CommandOption
  • func WithFileDescriptors(descriptors ...protoreflect.FileDescriptor) CommandOption
  • func WithReflection(args []string) CommandOption

Functions

func BuildCommand

func BuildCommand(cmd *cobra.Command, opts ...CommandOption) error

BuildCommand builds a grpctl command from a list of GrpctlOption.

func CommandFromFileDescriptor

func CommandFromFileDescriptor(cmd *cobra.Command, methods protoreflect.FileDescriptor) error

CommandFromFileDescriptor adds commands to cmd from a single FileDescriptor.

func CommandFromFileDescriptors

func CommandFromFileDescriptors(cmd *cobra.Command, descriptors ...protoreflect.FileDescriptor) error

CommandFromFileDescriptors adds commands to cmd from FileDescriptors.

func CommandFromMethodDescriptor

func CommandFromMethodDescriptor(cmd *cobra.Command, method protoreflect.MethodDescriptor) error

CommandFromMethodDescriptor adds commands to cmd from a MethodDescriptor. Commands added through this will have one level from the MethodDescriptors name.

func CommandFromServiceDescriptor

func CommandFromServiceDescriptor(cmd *cobra.Command, service protoreflect.ServiceDescriptor) error

CommandFromServiceDescriptor adds commands to cmd from a ServiceDescriptor. Commands added through this will have two levels: the ServiceDescriptor name as level 1 commands And the MethodDescriptors as level 2 commands.

func ReflectionCommand

func ReflectionCommand() (*cobra.Command, error)

ReflectionCommand returns the grpctl command that is used in the grpctl binary.

func WithStdin

func WithStdin(stdin io.Reader) func(cmd *cobra.Command) error

Types

type CommandOption

type CommandOption func(*cobra.Command) error

CommandOption are options to customize the grpctl cobra command.

func WithArgs

func WithArgs(args []string) CommandOption

WithArgs will set the args of the command as args[1:].

func WithCompletion

func WithCompletion() CommandOption

func WithContextDescriptorFunc

func WithContextDescriptorFunc(f func(context.Context, *cobra.Command, protoreflect.MethodDescriptor) (context.Context, error)) CommandOption

WithContextDescriptorFunc will modify the context before the main command is run but not in the completion stage.

func WithContextFunc

func WithContextFunc(f func(context.Context, *cobra.Command) (context.Context, error)) CommandOption

WithContextFunc will modify the context before the main command is run but not in the completion stage.

func WithFileDescriptors

func WithFileDescriptors(descriptors ...protoreflect.FileDescriptor) CommandOption

WithContextFunc will add commands to the cobra command through the file descriptors provided.

func WithReflection

func WithReflection(args []string) CommandOption

WithReflection will enable grpc reflection on the command. Use this as an alternative to WithFileDescriptors.