How to Install and Use grpcurl in Linux to Test and Debug gRPC Services

Modern microservice architectures frequently adopt gRPC (Google Remote Procedure Call) and Protocol Buffers (Protobuf) over traditional REST and JSON due to binary serialization speed, multiplexed HTTP/2 streaming, and strict interface definition contracts. However, because gRPC payloads are encoded in binary rather than plain text, developers cannot inspect or invoke RPC methods using standard curl or ordinary HTTP diagnostic tools.

grpcurl is an open-source command-line tool written in Go that serves as the curl equivalent for gRPC servers. It allows software engineers and DevOps professionals to query gRPC services, inspect remote schemas using gRPC Server Reflection, send JSON request bodies that are automatically converted to Protobuf on the wire, and test bidirectional streaming endpoints. This tutorial explains how to install grpcurl on Linux, discover services via reflection, invoke remote procedures, and manage TLS encryption.

What Makes grpcurl Indispensable?

Unlike REST APIs that expose human-readable endpoints, gRPC requires schema knowledge. grpcurl solves this through two flexible mechanisms:

• Server Reflection: If the target gRPC server has reflection enabled, grpcurl can dynamically query the server to list available services, methods, and Protobuf message structures without needing local .proto files.
• Local Proto Definitions: If server reflection is disabled in production environments, grpcurl can parse local .proto files and import paths directly from your project repository.
• Automatic JSON-Protobuf Translation: You provide input data formatted as familiar JSON, and grpcurl serializes it into binary Protobuf before dispatching it across the network.

Installing grpcurl on Linux

grpcurl is distributed across major Linux package managers, via Go, and as pre-compiled binaries.

Method 1: Install via Package Managers

Arch Linux:

sudo pacman -S grpcurl

Homebrew on Linux:

brew install grpcurl

Method 2: Install via Go

If you have the Go runtime configured:

go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest

Method 3: Install via Pre-Compiled Binary

On Ubuntu, Debian, or Fedora systems, download the official release archive from GitHub:

wget https://github.com/fullstorydev/grpcurl/releases/latest/download/grpcurl_linux_x86_64.tar.gz
tar -zxvf grpcurl_linux_x86_64.tar.gz
sudo mv grpcurl /usr/local/bin/

Verify that the binary executes properly:

grpcurl -version

Discovering Services Using gRPC Server Reflection

To list all exposed gRPC services running on a target host (using the -plaintext flag for unencrypted development servers):

grpcurl -plaintext localhost:50051 list

The server returns a list of registered services, such as:

grpc.reflection.v1alpha.ServerReflection
user.UserService
order.OrderService

To list all remote procedure methods available within a specific service:

grpcurl -plaintext localhost:50051 list user.UserService

To inspect the message schema and parameter requirements of a method:

grpcurl -plaintext localhost:50051 describe user.UserService.GetUser

Invoking gRPC Methods with JSON Payloads

To call an RPC method, pass the request payload formatted as a JSON string using the -d argument:

grpcurl -plaintext -d '{"user_id": "usr_99812"}' localhost:50051 user.UserService.GetUser

grpcurl serializes the JSON payload into binary Protobuf, executes the remote call over HTTP/2, and prints the server’s response back to the terminal formatted as clean, indented JSON:

{
  "user_id": "usr_99812",
  "username": "alex_turner",
  "email": "[email protected]",
  "status": "ACTIVE"
}

Using Local Proto Files When Reflection Is Disabled

If your target server disables gRPC reflection for security reasons, point grpcurl to your local Protobuf source definitions using the -import-path and -proto flags:

grpcurl -import-path ./protos -proto user.proto -d '{"user_id": "104"}' localhost:50051 user.UserService.GetUser

Managing TLS and Authentication Headers

When connecting to production endpoints protected by TLS and API tokens:

• Standard TLS: Omit the -plaintext flag to communicate over encrypted TLS automatically (e.g. grpcurl grpc.example.com:443 list).
• Custom CA Certificates: If using self-signed development certificates, supply the certificate file using -cacert /path/to/ca.crt or bypass verification with -insecure.
• Bearer Authentication Tokens: Inject OAuth or API keys using standard metadata headers with -H:

  grpcurl -H "Authorization: Bearer my_secret_jwt" grpc.example.com:443 order.OrderService.ListOrders