grpcurl is a command-line tool that lets you interact with gRPC servers. It's basically
curl for gRPC servers.
The main purpose for this tool is to invoke RPC methods on a gRPC server from the command-line. gRPC servers use a binary encoding on the wire (protocol buffers, or "protobufs" for short). So they are basically impossible to interact with using regular
curl (and older versions of
curl that do not support HTTP/2 are of course non-starters). This program accepts messages using JSON encoding, which is much more friendly for both humans and scripts.
With this tool you can also browse the schema for gRPC services, either by querying a server that supports service reflection or by loading in "protoset" files (files that contain encoded file descriptor protos). In fact, the way the tool transforms JSON request data into a binary encoded protobuf is using that very same schema. So, if the server you interact with does not support reflection, you will need to build "protoset" files that
grpcurl can use.
This code for this tool is also a great example of how to use the various packages of the protoreflect library, and shows off what they can do.
grpcurl supports all kinds of RPC methods, including streaming methods. You can even operate bi-directional streaming methods interactively by running
grpcurl from an interactive terminal and using stdin as the request body!
grpcurl supports both plain-text and TLS servers and has numerous options for TLS configuration. It also supports mutual TLS, where the client is required to present a client certificate.
As mentioned above,
grpcurl works seamlessly if the server supports the reflection service. If not, you must use
protoc to build protoset files and provide those to
Invoking an RPC on a trusted server (e.g. TLS without self-signed key or custom CA) that requires no client certs and supports service reflection is the simplest thing to do with
grpcurl. This minimal invocation sends an empty request body:
grpcurl grpc.server.com:443 my.custom.server.Service/Method
To list all services exposed by a server, use the "list" verb. When using protoset files instead of server reflection, this lists all services defined in the protoset files.
grpcurl localhost:8787 list grpcurl -protoset my-protos.bin list
The "list" verb also lets you see all methods in a particular service:
grpcurl localhost:8787 list my.custom.server.Service
The "describe" verb will print the type of any symbol that the server knows about or that is found in a given protoset file and also print the full descriptor for the symbol, in JSON.
grpcurl localhost:8787 describe my.custom.server.Service.MethodOne grpcurl -protoset my-protos.bin describe my.custom.server.Service.MethodOne
The usage doc for the tool explains the numerous options:
grpcurl on servers that do not support reflection, you need to compile the
*.proto files that describe the service into files containing encoded
FileDescriptorSet protos, also known as "protoset" files.
protoc --proto_path=. \ --descriptor_set_out=myservice.protoset \ --include_imports \ my/custom/server/service.proto
--descriptor_set_out argument is what tells
protoc to produce a protoset, and the
--include_imports arguments is necessary for the protoset to contain everything that
grpcurl needs to process and understand the schema.