grpcurl -d: Invoke a gRPC Method in CI
grpcurl -d '{...}' host:port service/Method calls a gRPC method with a JSON request and prints the JSON response.
This is the actual call. You pass the request as JSON with -d, name the method as service/Method, and grpcurl marshals it to protobuf and back for you.
What it does
grpcurl -d <json> invokes the named method with the given request message. The method is written package.Service/Method or package.Service.Method. Passing -d @ reads the JSON body from stdin. Metadata (gRPC headers) go in with -H "key: value". The response prints as JSON.
Common usage
grpcurl -plaintext -d '{"name": "Ada"}' \
localhost:50051 my.package.Greeter/SayHello
# request body from stdin
echo '{"name":"Ada"}' | grpcurl -plaintext -d @ \
localhost:50051 my.package.Greeter/SayHello
# with auth metadata
grpcurl -plaintext -H "authorization: Bearer $TOKEN" -d '{}' \
localhost:50051 my.package.Health/CheckOptions
| Flag | What it does |
|---|---|
| -d <json> | Request message as a JSON string |
| -d @ | Read the request JSON from stdin |
| -H "key: value" | Add request metadata (headers) |
| -plaintext | Cleartext connection (no TLS) |
| -max-time <sec> | Overall timeout for the call |
In CI
grpcurl exits non-zero when the RPC returns a non-OK status, so a call that returns codes.Unavailable or codes.Unauthenticated fails the step directly. That makes a single grpcurl -d a serviceable smoke test for a gRPC endpoint. Bound long calls with -max-time.
Common errors in CI
ERROR:\n Code: Unavailable\n Message: connection refused means the server is down. Code: NotFound\n Message: ... unknown method or Method not found means the service/Method name is wrong; verify with describe. Code: Unauthenticated means missing or invalid -H auth metadata. Error invoking method ... could not parse given request body as message means the -d JSON does not match the request type.