grpcurl: Usage, Options & Common CI Errors
grpcurl calls gRPC methods from the command line, like curl for gRPC.
grpcurl is the standard way to smoke-test a gRPC endpoint in CI. The two recurring failures are server reflection not being enabled and forgetting -plaintext on a non-TLS port.
What it does
grpcurl invokes gRPC methods over the wire, listing and describing services via server reflection or local .proto files, and sends JSON request bodies that it marshals to protobuf. It is the gRPC equivalent of curl for scripted health checks.
Common usage
grpcurl -plaintext localhost:50051 list # list services
grpcurl -plaintext localhost:50051 describe my.Svc
grpcurl -plaintext -d '{"id":"1"}' localhost:50051 my.Svc/Get
grpcurl -import-path ./proto -proto my.proto -d '{}' host:443 my.Svc/Get
grpcurl host:443 grpc.health.v1.Health/Check # standard health probeOptions
| Flag | What it does |
|---|---|
| -plaintext | Use plaintext (no TLS) - required for non-TLS ports |
| -d <json> | Request body as JSON (- reads from stdin) |
| -import-path / -proto | Resolve methods from local .proto files |
| -H "k: v" | Add a request metadata header |
| -insecure | Use TLS but skip certificate verification |
| list / describe | Enumerate / introspect services and methods |
Common errors in CI
Failed to dial target host ... server does not support the reflection API - the server has not registered grpc.reflection; supply the schema with -import-path/-proto instead, or enable reflection. "Failed to dial ... tls: first record does not look like a TLS handshake" means the port is plaintext - add -plaintext. "rpc error: code = Unimplemented" means the service/method name is wrong (it is package.Service/Method, case-sensitive). "code = Unavailable ... connection refused" means nothing is listening on that host:port yet.
Using this in CI
A runner shell is not a login shell. It does not read your dotfiles, it usually has no TTY, and by default it does not stop on the first error, so a failing command in the middle of a multi-line run block can leave the job green.
# make the shell behave the way you assume it does
- name: Build
shell: bash
run: |
set -euo pipefail # exit on error, undefined vars, and pipeline failures
./do-the-thing | tee out.log