grpcurl list: Discover Services and Methods in CI
grpcurl list shows the services a server exposes and grpcurl describe shows a service or message schema, both via server reflection.
Before calling a method you often need to know what is registered. grpcurl list enumerates services; describe drills into methods and message fields.
What it does
With no method argument, grpcurl list returns the set of services from the server reflection API; grpcurl list <service> lists that service's methods. grpcurl describe <symbol> prints the proto definition of a service, method, or message. All of this requires reflection unless you supply -proto/-protoset.
Common usage
# list all services
grpcurl -plaintext localhost:50051 list
# list methods of one service
grpcurl -plaintext localhost:50051 list acme.api.v1.UserService
# describe a service or a message type
grpcurl -plaintext localhost:50051 describe acme.api.v1.UserService
grpcurl -plaintext localhost:50051 describe .acme.api.v1.GetUserRequestFlags and options
| Command / flag | What it does |
|---|---|
| list | List all services exposed by the server |
| list <service> | List the methods of one service |
| describe <symbol> | Print the proto definition of a symbol |
| -plaintext | Cleartext HTTP/2 (no TLS) |
| -msg-template | With describe, also print an empty request template |
| -protoset / -proto | Use descriptors/protos instead of reflection |
In CI
Use grpcurl list as a lightweight post-deploy assertion that the expected services registered. Combine with -msg-template on describe to generate a starter JSON body for a follow-up grpcurl call in the same script.
Common errors in CI
"Failed to list services: server does not support the reflection API" means reflection is not enabled in the server build; either enable it or pass -protoset/-proto. "Failed to resolve symbol "acme.api.v1.UserService": Symbol not found" with describe means the name is misspelled or not registered. "connection refused" means the server or port is wrong.