grpcurl list: Discover gRPC Services via Reflection
grpcurl -plaintext host:port list prints the gRPC services a server exposes, using server reflection.
grpcurl is curl for gRPC. list is the first thing you run against a new server: with reflection enabled it enumerates the services, and listing a service enumerates its methods.
What it does
grpcurl list queries the server's reflection service to print the fully qualified service names it exposes. grpcurl list <service> lists that service's methods. -plaintext disables TLS for a cleartext gRPC port; without it grpcurl attempts a TLS handshake.
Common usage
grpcurl -plaintext localhost:50051 list
grpcurl -plaintext localhost:50051 list my.package.Greeter
# against a TLS endpoint (no -plaintext)
grpcurl grpc.example.com:443 listOptions
| Flag | What it does |
|---|---|
| -plaintext | Use cleartext (no TLS) for the connection |
| list [service] | List services, or methods of a service |
| -import-path / -proto | Use local .proto files instead of reflection |
| -H "key: value" | Add a request metadata header |
| -max-time <sec> | Overall timeout for the call |
In CI
If the server does not expose reflection, supply the schema locally with -proto and -import-path instead of list-based discovery. Use -plaintext for in-cluster cleartext ports and omit it for TLS endpoints; mismatching the two is the most common first error.
Common errors in CI
Failed to dial target host "localhost:50051": connection refused means nothing is listening; wait for the port first. Failed to list services: server does not support the reflection API means reflection is off, so use local .proto files. Omitting -plaintext on a cleartext port gives tls: first record does not look like a TLS handshake.