grpcurl
A command-line tool for calling gRPC servers, similar to how curl works for HTTP.
- Stars
- 12.9k
- Forks
- 587
- Licence
- MIT
- Language
- Go
- Last update
- 24 days ago
- Type
- CLI
What it is
grpcurl is a command-line tool for sending requests to gRPC servers and seeing their responses. gRPC uses a binary format that standard curl cannot read, so grpcurl lets you write requests in JSON and converts them for you. It can discover a server's available services if the server supports reflection, or it can use proto source files or protoset files you provide.
- List the services a server exposes with the list command
- Send a JSON request body to a specific RPC method
- Pipe JSON generated by jq into a gRPC call using -d @
- Add custom headers or metadata to a request with -H
- Export a service's proto definitions with describe and -proto-out-dir
Great for
- Backend engineers testing gRPC endpoints during development
- Developers debugging a gRPC service from the terminal
- Teams writing shell scripts or pipelines that call gRPC services
- Anyone who needs to explore a gRPC server's available methods
Not ideal for
- People who only work with plain HTTP REST APIs, since it is specific to gRPC
- Users who need a graphical interface rather than a command line
- Cases where the server has no reflection and no proto or protoset files are available, because grpcurl cannot know the message structure without them
How to get it
- 1
Install with a package manager
You'll need: Homebrew for the macOS install option, or Docker for the container option · Go SDK if installing from source
Install on macOS with Homebrew
brew install grpcurlInstall from source with Go
go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest - 2
Run it
- Install grpcurl using one of the methods in the README
- Run grpcurl -help to see available options
- List services on a server with: grpcurl localhost:8787 list
- Send a request with -d, for example: grpcurl -d '{"id": 1234}' grpc.server.com:443 my.custom.server.Service/Method
- 3
Get the most out of it
- Use -plaintext for servers without TLS and provide certificate options for TLS or mutual TLS
- Use -H to add headers or metadata to requests
- Pipe JSON from jq into grpcurl with -d @ for scripted requests
- Use describe with -proto-out-dir or -protoset-out to export schemas for offline use
Downloads
Strengths
- Uses familiar JSON for request bodies instead of binary protobuf
- Supports streaming methods, TLS, plain-text, and mutual TLS
- Works with server reflection, proto source files, or protoset files
Trade-offs
- Needs schema information (reflection, proto files, or protoset) to work with most servers
- Some Docker usage requires extra setup for networking and file mounts, as the README notes
How it compares
| Project | Stars | Type | Level | Updated | Best for |
|---|---|---|---|---|---|
| grpcurl (this) | 12.9k | CLI | beginner | 24 days ago | Backend engineers testing gRPC endpoints during development |
| kratos | 26k | Library | intermediate | 5 days ago | Go developers building a set of backend services that talk over HTTP or gRPC |
| pocketbase | 61.6k | App | beginner | 11 days ago | Developers building a small web or mobile app who want a ready-made backend |
| cli | 46.8k | CLI | beginner | 7 days ago | Developers who already work in the terminal and use GitHub daily |
| croc | 40.8k | CLI | beginner | 4 days ago | People who need to send a file to someone without setting up a server, accounts, or port forwarding |
| go-zero | 33.4k | Library | intermediate | 5 days ago | Go developers building REST APIs or microservices |
Stats synced from GitHub. The assessment above was drafted with AI from the project's README on 2026-10-29 and may miss recent changes — check the README before relying on a command. MIT licence: free to use, modify and distribute, including commercially, as long as you keep the copyright notice.