grpcurl — Command-Line Client for gRPC Services

Introduction

grpcurl is a command-line tool that lets you interact with gRPC servers the same way curl works for REST APIs. It removes the need to generate client stubs or write code just to test and debug gRPC endpoints.

What grpcurl Does

• Invokes unary, server-streaming, client-streaming, and bidirectional RPCs from the terminal
• Discovers available services and methods via gRPC server reflection
• Accepts proto source files or compiled descriptor sets when reflection is unavailable
• Sends and receives JSON-encoded protobuf messages
• Supports TLS, mutual TLS, and plaintext connections

Architecture Overview

grpcurl is a single Go binary that acts as a generic gRPC client. It uses the protobuf dynamic message library to serialize JSON input into the wire format defined by the target service's schema. When server reflection is enabled, it fetches service descriptors at runtime; otherwise it reads .proto files or precompiled FileDescriptorSets from disk.

Self-Hosting & Configuration

• Install via go install, Homebrew, or download prebuilt binaries from GitHub releases
• Use -plaintext for non-TLS development servers
• Supply -proto flags to point at .proto source files when reflection is off
• Pass -H for custom metadata headers (e.g., authorization tokens)
• Pipe JSON from stdin with -d @ for scripted calls in CI pipelines

Key Features

• curl-like simplicity for the gRPC ecosystem
• Full support for all four gRPC streaming patterns
• Automatic service discovery through server reflection
• Works with any language's gRPC server implementation
• Single static binary with zero runtime dependencies

Comparison with Similar Tools

• Evans — interactive TUI gRPC client; grpcurl is better for scripting and CI
• BloomRPC / Postman — GUI-based gRPC clients; grpcurl runs entirely in the terminal
• buf curl — part of the Buf CLI with similar goals; grpcurl is standalone and widely adopted
• grpc_cli — official gRPC project tool; grpcurl has richer output and easier installation
• Kreya — desktop IDE for gRPC and REST; grpcurl targets automation and pipelines

FAQ

Q: Does the gRPC server need to enable reflection? A: Reflection makes discovery automatic, but you can supply .proto files or descriptor sets instead if reflection is disabled.

Q: Can I test streaming RPCs? A: Yes. For client streaming, pipe multiple JSON objects separated by newlines. For server streaming, grpcurl prints each response as it arrives.

Q: How do I pass authentication headers? A: Use the -H flag, e.g., -H "Authorization: Bearer ", just like setting HTTP headers with curl.

Q: Does grpcurl support gRPC-Web? A: No. grpcurl uses the native HTTP/2-based gRPC protocol. For gRPC-Web, you need a proxy like Envoy.

Sources

• https://github.com/fullstorydev/grpcurl
• https://pkg.go.dev/github.com/fullstorydev/grpcurl