grpcurl: Call a gRPC Method From CI

grpcurl calls a gRPC method from the shell: pass the request body as JSON with -d and the fully qualified service/method as the final argument.

grpcurl is curl for gRPC. In CI smoke tests it confirms a freshly deployed service actually answers an RPC, not just that the port is open.

What it does

grpcurl connects to host:port, serializes the JSON you give -d into the request message, invokes the named package.Service/Method, and prints the response as JSON. It discovers the schema via server reflection by default, or from .proto/descriptor files you provide.

Common usage

Terminal

# plaintext (no TLS), JSON request body, reflection
grpcurl -plaintext -d '{"id": "42"}' \
  localhost:50051 acme.api.v1.UserService/GetUser

# read JSON request from stdin
echo '{"id":"42"}' | grpcurl -plaintext -d @ \
  localhost:50051 acme.api.v1.UserService/GetUser

# without reflection: point at proto files
grpcurl -plaintext -import-path proto -proto api/v1/user.proto \
  -d '{"id":"42"}' localhost:50051 acme.api.v1.UserService/GetUser

Flags and options

Flag	What it does
-d <json>	Request body as JSON; -d @ reads from stdin
-plaintext	Use cleartext HTTP/2 (no TLS)
-insecure	Use TLS but skip certificate verification
-H "key: value"	Add a request metadata header (repeatable)
-import-path <dir> / -proto <file>	Use .proto files instead of reflection
-protoset <file>	Use a compiled FileDescriptorSet instead of reflection
-max-time <sec>	Overall timeout for the call

In CI

Pipe the JSON via -d @ to keep complex bodies out of the shell-quoting minefield. Use -plaintext only against in-cluster services; for public endpoints rely on real TLS and reserve -insecure for self-signed test certs. Wrap the call in -max-time so a hung server fails the job promptly.

Common errors in CI

"Failed to dial target host "localhost:50051": connection refused" means the server is not up or the port is wrong. "Failed to compute set of methods to expose: server does not support the reflection API" means reflection is off; pass -proto/-protoset. "Error invoking method ...: ... Unimplemented" means the method name is wrong or the service is not registered. "x509: certificate signed by unknown authority" on TLS means a missing CA; add -cacert or -insecure for tests.