gRPCurl - Command-Line
Tool for Testing gRPC Services
gRPCurl is a command-line tool for testing and interacting with gRPC services, offering features like reflection, requests, and response debugging.
Key Features
Command Line
grpcurl is a command-line tool that lets you interact with gRPC servers directly without writing any client code or compiling stubs.
No Stubs
It works without needing generated client code; just provide the proto file or use server reflection to call any gRPC endpoint.
Server Reflection
Supports gRPC server reflection to auto-discover available services and methods without local .proto files.
JSON Requests
Send and receive messages in simple JSON format, making it easy to interact with gRPC services using human-readable input.
Service Listing
Quickly list all available services on a gRPC server to explore what’s exposed and ready for interaction or testing.
TLS Support
Connect to secure gRPC servers with TLS encryption and certificate support for safe communication over networks.
Installation Method
Troubleshoot
Check Reflection
- If grpcurl can't list services, the server may not enable reflection; use .proto files to interact manually.
Use Proto
- Without reflection, supply the correct .proto files and import paths to help grpcurl understand the service structure.
Invalid Format
- Malformed JSON input causes execution failure; always validate your payload format using tools like jq before sending.
Missing Fields
- Ensure all required fields match the method definition in your .proto file to avoid decoding and validation errors.
Server Reachability
- Connection problems often mean the server isn't running or the address is wrong; double-check the host and port.
Secure Access
- If using TLS, include -plaintext for insecure connections or provide certificates when accessing secure gRPC endpoints.
Authentication and TLS
TLS Authentication
Enable secure communication between grpcurl and gRPC server using TLS encryption with optional certificate verification.
Enable TLS
Use -tls to initiate a secure connection. This encrypts data in transit to protect from eavesdropping or tampering. "grpcurl -tls <host>:<port> list"
Skip Verify
Use -insecure if the server uses self-signed or untrusted certificates to skip TLS verification (not recommended in production)."grpcurl -tls -insecure : list "
CA Certificate
Use -cacert to specify a custom CA certificate for verifying server identity against a private or custom certificate authority. "grpcurl -tls -cacert ca.pem : list "
Client Certificate
Use -cert and -key to provide client certificates when mutual TLS (mTLS) is required by the server for authentication."grpcurl -tls -cert client.pem -key client.key : list "
Why Choose grpcurl
Grpcurl is Lightweight, fast, and curl-like gRPC testing made easy
Frequently Asked Questions (FAQS)
What is grpcurl?
grpcurl is a command-line tool for making gRPC requests. It functions similarly to curl, but for gRPC services.
Who maintains grpcurl?
grpcurl is an open-source project developed and maintained by FullStory and the community on GitHub.
Is grpcurl cross-platform?
Yes, grpcurl is available for Linux, macOS, and Windows.
What are the common use cases for grpcurl?
- Testing gRPC endpoints
- Debugging gRPC services
- Interacting with gRPC servers without writing code
How do I install grpcurl?
You can download pre-built binaries from the GitHub releases page or use Homebrew on macOS (brew install grpcurl).
Does grpcurl Does grpcurl require a .proto file?a .proto file?
Not always. If the gRPC server supports server reflection, you can use grpcurl without a .proto file.
How do I use a .proto file with grpcurl?
Use the -import-path and -proto flags to specify the location and name of the .proto file.
How do I list all services on a gRPC server?
Use: grpcurl [host:port] list
How do I list methods in a particular service?
Use: grpcurl [host:port] list [ServiceName]
How do I describe a service or method?
Use: grpcurl [host:port] describe [ServiceName/MethodName]
How do I invoke a gRPC method?
Use: grpcurl -d ‘{“field”: “value”}’ [host:port] [ServiceName/MethodName]
How do I make a secure (TLS) request with grpcurl?
Use the -proto, -import-path, and -plaintext or -insecure flags depending on your security needs.
Can grpcurl handle streaming RPCs?
Yes, it supports both client-streaming and server-streaming, though client-streaming is more limited.
Can I authenticate with grpcurl?
Yes. Use flags like -H to set custom headers (e.g., authorization) for token-based authentication.
How do I set custom headers in grpcurl?
grpcurl -H “Authorization: Bearer TOKEN” …
Does grpcurl support JSON input/output?
Yes, it uses JSON for both requests and responses, making it user-friendly.
Can I use grpcurl with non-reflection servers?
grpcurl is a command-line tool for making gRPC requests. It functions similarly to curl, but for gRPC services.
Why am I getting an "unknown service" error?
This might occur if server reflection is disabled or the .proto files are not provided correctly.
What does the -plaintext flag do?
It disables TLS encryption. Use it only with trusted, internal servers.
How can I debug or log more info during execution?
Use the -v (verbose) flag to see more detailed request and response data.