grpcurl

Send an empty request

$ grpcurl [grpc.server.com:443] [my.custom.server.Service/Method]

$ grpcurl -H "[Authorization: Bearer $token]" -d ['{"foo": "bar"}'] [grpc.server.com:443] [my.custom.server.Service/Method]

$ grpcurl [grpc.server.com:443] list

$ grpcurl [grpc.server.com:443] list [my.custom.server.Service]

grpcurl [GLOBAL_OPTIONS] [CONNECTION_OPTIONS] [CALL_OPTIONS] ADDRESS [METHOD | list | describe [SYMBOL]]

--help
    Displays help information for grpcurl or a specific subcommand.

-v, --verbose
    Shows extra details about the RPC, including request/response headers and connection information.

-plaintext
    Connects to the server without using TLS (plain text HTTP/2).

-insecure
    Skips TLS certificate verification. Useful for development or self-signed certificates.

-d, --data <string>
    Provides the request message body, typically as a JSON string or a file path (prefixed with '@').

-H, --header <name:value>
    Adds a custom HTTP header to the request (e.g., for Authorization or content-type).

-rpc-header <name:value>
    Adds a gRPC metadata header to the request, which is passed along with the gRPC call.

-proto <file>
    Specifies the path to .proto source files to load service definitions when reflection is not available.

-protoset <file>
    Specifies the path to a compiled FileDescriptorSet (protoset) file containing service definitions.

-max-time <duration>
    Sets the maximum time the call is allowed to take before it is cancelled (e.g., '5s', '1m').

grpcurl is a command-line tool designed for interacting with gRPC servers, providing a curl-like experience tailored specifically for gRPC. It enables developers and testers to send gRPC requests, inspect responses, and explore service definitions directly from their terminal.

A key feature of grpcurl is its robust support for gRPC server reflection, which allows it to query a gRPC server for its service and method definitions without requiring local .proto files. This capability significantly simplifies the testing and debugging of gRPC services.

When server reflection is not enabled, grpcurl can also utilize local .proto files or pre-compiled descriptor sets to understand the service schema. It supports various message formats, including JSON for request payloads and response display, making it intuitive to work with. Furthermore, grpcurl handles different authentication mechanisms, including TLS/SSL for secure communication and client-side certificates for mutual TLS. It is an indispensable tool for anyone working with gRPC-based microservices, offering powerful capabilities for development, testing, and troubleshooting.

While grpcurl's server reflection capability is powerful, not all gRPC servers enable reflection (e.g., for security or performance reasons). In such cases, you must provide local .proto files or pre-compiled protoset files for grpcurl to understand the service schema. Additionally, interacting with client-streaming or bi-directional streaming RPCs can be more complex, requiring multiple input messages to be provided to grpcurl.

grpcurl's most distinctive and powerful feature is its ability to interact with gRPC servers that expose the server reflection service. This allows grpcurl to dynamically discover available services, methods, and their message schemas without needing any local .proto files. This capability significantly streamlines development and testing workflows, eliminating the need to manually manage protobuf definitions on the client side.

For request payloads, grpcurl primarily accepts data in JSON format, which is automatically converted to the appropriate Protobuf message format before being sent to the server. For complex messages or nested structures, grpcurl can also generate a JSON template for a given method using the -msg-template option. This feature greatly simplifies the creation of accurate request payloads by providing a pre-filled structure with default values.

grpcurl was developed by FullStory as a practical, open-source command-line solution to interact with gRPC services. It emerged to address the growing need for a curl-like tool specifically designed for the gRPC protocol, filling a significant gap in the ecosystem. Its focus on server reflection capabilities quickly made it a widely adopted and invaluable tool for developers and engineers working with gRPC-based microservices, simplifying development, testing, and debugging workflows.

curl(1), netcat(1), openssl(1), protoc