README

gRPCurl




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 server reflection,
by reading proto source files, or by loading in compiled "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 either need the proto source files that define the service or need
protoset files that grpcurl can use.

This repo also provides a library package, github.com/fullstorydev/grpcurl, that has
functions for simplifying the construction of other command-line tools that dynamically
invoke gRPC endpoints. This code is a great example of how to use the various packages of
the protoreflect library, and shows
off what they can do.

See also the grpcurl talk at GopherCon 2018.

 Features
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 secure/TLS servers _and_ plain-text servers (i.e. no TLS) 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 can supply the .proto source files or you can supply protoset
files (containing compiled descriptors, produced by protoc) to grpcurl.

 Installation

 Binaries

Download the binary from the releases page.

 Homebrew (macOS)

On macOS, grpcurl is available via Homebrew:
shell
brew install grpcurl


 Docker

For platforms that support Docker, you can download an image that lets you run grpcurl:
shell
 Download image
docker pull ghcr.io/fullstorydev/grpcurl:latest
 Run the tool
docker run ghcr.io/fullstorydev/grpcurl api.grpc.me:443 list

Note that there are some pitfalls when using docker:
- If you need to interact with a server listening on the host's loopback network, you must specify the host as host.docker.internal instead of localhost (for Mac or Windows) _OR_ have the container use the host network with -network="host" (Linux only).
- If you need to provide proto source files or descriptor sets, you must mount the folder containi