joshcarp / grpctl

Quickly generate a gRPC CLI or use gRPC reflection with ease

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.