grpcurl: Reflection vs Proto Files in CI
grpcurl resolves message schemas either from the server reflection API (default) or from local .proto files (-proto) or a compiled descriptor set (-protoset).
Reflection is convenient but is often disabled in production. Knowing how to feed grpcurl local descriptors keeps your CI checks working against hardened servers.
What it does
By default grpcurl asks the server for its schema over the reflection service. If the server does not expose reflection, you supply the schema yourself: -proto plus -import-path parse source .proto files, while -protoset reads a precompiled FileDescriptorSet (for example one built by buf build --as-file-descriptor-set or protoc --descriptor_set_out).
Common usage
# reflection (default): nothing extra needed
grpcurl -plaintext localhost:50051 list
# from .proto source files
grpcurl -plaintext -import-path proto -proto api/v1/user.proto \
localhost:50051 list
# from a compiled descriptor set
buf build -o image.binpb --as-file-descriptor-set
grpcurl -plaintext -protoset image.binpb localhost:50051 listFlags and options
| Flag | What it does |
|---|---|
| (none) | Default: resolve schema via server reflection |
| -import-path <dir> | Root for resolving proto imports (repeatable) |
| -proto <file> | Parse this .proto file for the schema (repeatable) |
| -protoset <file> | Read a compiled FileDescriptorSet |
| -use-reflection | Force reflection even when -proto/-protoset are given |
In CI
Build a descriptor set once (buf build --as-file-descriptor-set or protoc --descriptor_set_out) and pass it with -protoset; that decouples your check from whether the target enables reflection and is faster than re-parsing .proto files each call.
Common errors in CI
"server does not support the reflection API" is the signal to switch to -proto/-protoset. "Failed to process proto source files ... no such file or directory" means -import-path does not contain the imported files. "could not parse contents of protoset file" means the file is not a valid FileDescriptorSet (you passed a buf image without --as-file-descriptor-set, or a code-gen output).