PROVIDER - Debug gRPC services from the command line

grpcurl

grpcurl calls gRPC services with 1 command without generated clients, using reflection to list 2 or more layers of services, JSON in and out, and TLS, mTLS or custom headers across 3 auth scenarios as a BSD single binary; the gaps are gRPC-only scope and streaming flag complexity.

Developer Tools United States 2026.11.19
4.1pts

Detailed Notes

Pros 5 items

Calls gRPC services with 1 command and no generated client code
Supports reflection to list 2 or more layers of services and methods directly
Accepts and returns JSON, matching the 2 habits familiar from REST tooling
Covers 3 common auth scenarios with TLS, mTLS and custom headers
Released under a BSD licence as 1 single cross-platform binary

Cons 4 items

Targets gRPC only, with no REST or GraphQL support
Streaming calls take many flags, raising the learning cost
No GUI, so sharing cases across a team is awkward
Relies on server reflection or supplied proto files

Service Overview

grpcurl is Fullstory's open source gRPC command line client that calls gRPC services much like curl calls HTTP endpoints.

In the development tools category it is interface debugging tooling, filling the gap for a lightweight gRPC CLI client.

Key Strengths

  • No code required: 1 command to call
  • Reflection support: explore without protos
  • JSON friendly: readable payloads
  • Auth coverage: TLS and mTLS
  • Single binary: no dependencies

Product Ecosystem

Platform capabilities

Service and method listing, request description, unary and streaming calls, JSON to proto conversion, TLS and header configuration plus error detail parsing.

Integrations

Works with kubectl port forwarding, Docker, CI scripts and service mesh debugging flows.

Typical scenarios

Microservice troubleshooting, gRPC smoke tests, verifying services inside Kubernetes and debugging auth chains.

Limitations

  • Protocol scope: gRPC only
  • Learning cost: streaming flags add complexity
  • No GUI: sharing is manual
  • Prerequisites: reflection or protos needed

Use Cases

  • Fast gRPC troubleshooting (★★★★★): the core scenario
  • In-cluster verification (★★★★☆): port forwarding fits
  • CI smoke tests (★★★★☆): easy to script
  • REST endpoint debugging (★☆☆☆☆): not applicable

Pricing

Item Price Notes
grpcurl $0 BSD licence, free and open source
Installation $0 brew, go install or binary download
Usage cost $0 No licence or seat limits

FAQ

What if reflection is disabled?

Point grpcurl at proto files or import paths with -proto.

Does it support streaming?

Client streaming, server streaming and bidirectional streaming all work.

Can it be used inside Kubernetes?

Yes, commonly with kubectl port-forward or directly inside a pod.

How does it relate to grpcui?

grpcui provides a web UI and belongs to the same project family.

Code Examples

# List services (server reflection required)
grpcurl -plaintext localhost:50051 list

# Describe a method
grpcurl -plaintext localhost:50051 describe demo.OrderService.GetOrder

# Make a call
grpcurl -plaintext -d '{"id": 1}' localhost:50051 demo.OrderService/GetOrder

# With TLS and a custom header
grpcurl -H 'Authorization: Bearer <token>' \
  api.example.com:443 demo.OrderService/GetOrder
# Combine with Kubernetes port forwarding
kubectl port-forward svc/order-api 50051:50051 &
grpcurl -plaintext -d '{"id": 1}' localhost:50051 demo.OrderService/GetOrder

Community & Resources

Visit grpcurl Website → https://github.com/fullstorydev/grpcurl
Visit Website ↗