grpcurl

List services on a gRPC server (with reflection)

$ grpcurl [localhost:50051] list

$ grpcurl [localhost:50051] describe [package.ServiceName]

$ grpcurl -d '{"name": "[value]"}' [localhost:50051] [package.Service/Method]

$ grpcurl -proto [service.proto] -d '{"id": 1}' [localhost:50051] [package.Service/Method]

$ grpcurl -plaintext [localhost:50051] [package.Service/Method]

$ grpcurl -H "Authorization: Bearer [token]" [localhost:50051] [package.Service/Method]

$ grpcurl -d @ [localhost:50051] [package.Service/Method] < [data.json]

$ grpcurl [localhost:50051] list [package.ServiceName]

grpcurl [options] target [method] [request]

grpcurl is a command-line tool for interacting with gRPC servers, similar to how curl works for HTTP APIs. It can invoke RPC methods, inspect services, and help debug gRPC-based applications.
The tool can discover services in two ways: server reflection (where the server describes its own API) or by providing proto files. Reflection is convenient but must be enabled on the server. Proto files work with any server but require having the service definitions.
For unary calls, request data is provided as JSON via the -d flag. Streaming calls can read multiple messages from stdin. Response data is output as JSON by default, making it easy to parse with jq or other tools.
grpcurl handles the complexity of gRPC's HTTP/2 transport, protobuf encoding, and TLS. The -plaintext flag is needed for non-TLS servers (common in development). For production servers with TLS, proper certificates may be required.

-d data

Request data as JSON string (use @ to read from stdin).

Proto file defining the service (alternative to reflection).

Pre-compiled proto descriptor file.

Path to search for proto imports.

Use plaintext (no TLS) connection.

Skip TLS certificate verification.

Add header as "name: value" (repeatable).

Add gRPC metadata header.

Set :authority pseudo-header.

Connection timeout.

Maximum time for the call.

Output format: json (default) or text.

Verbose output (show headers).

List services or methods.

Describe service, method, or message.

Server must have reflection enabled for discovery, or proto files must be provided. JSON representation of protobuf has edge cases (especially with bytes, enums, and 64-bit integers). Streaming calls have different interaction patterns. Some gRPC features like deadlines need explicit configuration.

grpcurl was created by FullStory Inc. and released as open-source. It emerged from the need for a curl-equivalent for the gRPC ecosystem, which was gaining adoption for microservices communication. The tool is written in Go and uses the official gRPC-Go libraries.

curl(1), protoc(1), grpc_cli(1), evans(1)