explaingit

fullstorydev/grpcurl

★ 12,632GoAudience · developerComplexity · 2/5Setup · easy

TLDR

A command-line tool for calling gRPC server endpoints from the terminal, like cURL for HTTP. It converts human-readable JSON to binary protobuf format and back automatically.

Mindmap

mindmap
  root((grpcurl))
    What it does
      Call gRPC methods
      JSON to protobuf
      Streaming support
    Service discovery
      Server reflection
      Proto source files
      Descriptor files
    Connection types
      TLS encrypted
      Plain text
      Mutual TLS
    Installation
      Binary download
      Homebrew macOS
      Docker image
    Go library
      Build custom clients
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Things people build with this

USE CASE 1

Test a gRPC service endpoint from your terminal without writing any client code.

USE CASE 2

List all services and methods available on a gRPC server using server reflection.

USE CASE 3

Debug bidirectional streaming gRPC methods by piping JSON messages from a file.

USE CASE 4

Automate gRPC API calls in shell scripts using JSON input piped from other commands.

Tech stack

Go

Getting it running

Difficulty · easy Time to first run · 5min

In plain English

gRPCurl is a command-line tool for talking to gRPC servers, named after the popular cURL utility that developers use to send HTTP requests from the terminal. gRPC is a way for programs to communicate with each other over a network, but it uses a compact binary data format called protocol buffers (protobuf) that is not human-readable and cannot be sent with regular HTTP tools. gRPCurl translates between the JSON format humans can read and write and the binary format that gRPC servers expect. With gRPCurl you can call any method on a gRPC server, including streaming methods where the server sends back multiple responses over time, or where both sides exchange data back and forth in an ongoing conversation. You write the request data as JSON in the terminal or pipe it in from another command, and the tool handles the conversion automatically. Custom headers and metadata can be added to each request with a flag. To know what methods and data shapes a server accepts, gRPCurl can ask the server directly if it supports a feature called server reflection. If the server does not support reflection, you can point gRPCurl at the source files that define the service (proto files) or pre-compiled descriptor files. This lets you list available services and describe what fields each method expects before making a call. Installation options include downloading a pre-built binary, using Homebrew on macOS, running it as a Docker container, installing via the Snap package manager, or building from source if you have Go installed. The tool supports servers that use TLS encryption, plain unencrypted connections, or mutual TLS where both the client and server present certificates to each other. The repository also includes a Go library package that other developers can use as a base for building their own gRPC command-line clients.

Copy-paste prompts

Prompt 1
Using grpcurl, how do I call the SayHello method on a gRPC server at localhost:50051 with the JSON payload {"name": "World"}?
Prompt 2
How do I list all available services on a gRPC server using grpcurl and server reflection?
Prompt 3
Show me how to use grpcurl with a .proto file to describe a service and call one of its methods.
Prompt 4
How do I connect grpcurl to a gRPC server that requires mutual TLS, providing both client certificate and key?
Prompt 5
Write a shell script that calls a gRPC endpoint with grpcurl and pipes the JSON response to jq to extract a specific field.
Open on GitHub → Explain another repo

← fullstorydev on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.