Guide · Open source
How to use grpcurl: send gRPC requests from the terminal
Updated · written with AI from the project's own documentation and checked against our catalogue data
grpcurl is an open-source command-line tool for sending requests to gRPC servers and reading their responses, often described as curl for gRPC. It is aimed at backend engineers and developers who test or debug gRPC services from the terminal or from scripts. After this guide you will be able to install grpcurl, list and describe a server's services, and send a JSON request to a method.
grpcurlfullstorydev/grpcurl · ★ 12.9k · MIT Install options & downloads Quick start
- 1Install grpcurl. On macOS, run brew install grpcurl. If you have the Go SDK, you can instead use go install with the cmd/grpcurl path.
- 2Check the help. Run grpcurl -help to see all options and TLS settings.
- 3List the services. Run grpcurl with the server address and list. Use -protoset or -proto if the server has no reflection.
- 4Describe a symbol. Use describe with a service or method name to see its structure.
- 5Send a JSON request. Pass the body with -d and the method as service/Method after the address. Add -plaintext for servers without TLS.
- 6Add headers if needed. Use -H name:value to send metadata with the request.
What grpcurl is and when you need it
gRPC servers exchange messages in protocol buffers, a binary encoding. Regular curl cannot read or write that format, so it is not useful for calling gRPC methods. grpcurl accepts request bodies in JSON, which is easier for people and scripts to write, and converts them to the binary format before sending.
grpcurl is specific to gRPC. If you only work with plain HTTP REST APIs, or you need a graphical interface rather than a command line, it is not the right fit.
Install grpcurl on macOS, Docker or from source
On macOS, install grpcurl with Homebrew. Other options in the project README are downloading a binary from the releases page, using a Docker image, or installing a snap package. If you already have the Go SDK, you can install from source. The command installs into the bin folder of your GOPATH, or $HOME/go/bin if GOPATH is not set, so that folder should be on your PATH.
- macOS: Homebrew (requires Homebrew)
- Docker: a container image is available (requires Docker)
- From source: requires the Go SDK
- Snap: snap install grpcurl
- Other packages are listed at repology.org
brew install grpcurl
go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latestCheck the available options
grpcurl has many options, including TLS settings. The built-in help lists them all, and it is the best reference when you are unsure of a flag.
grpcurl -helpList services and methods on a server
The list verb shows the services a server exposes. If the server supports server reflection, you only need the address. If you use proto source files or protoset files instead, list shows the services defined in those files. Adding a service name shows the methods inside it.
# Server supports reflection
grpcurl localhost:8787 list
# Using compiled protoset files
grpcurl -protoset my-protos.bin list
# Using proto sources
grpcurl -import-path ../protos -proto my-stuff.proto list
# Methods in one service
grpcurl localhost:8787 list my.custom.server.ServiceDescribe a service or message
The describe verb prints the type of a symbol the server knows about, or one found in a protoset file, along with proto-style snippets describing it. The output is equivalent to the original definition, though not necessarily the same text. You can also export the proto files or a protoset file from a running server.
- -proto-out-dir sets the output directory for exported proto files
- -protoset-out sets the output file for an exported protoset
grpcurl localhost:8787 describe my.custom.server.Service.MethodOne
grpcurl -plaintext -proto-out-dir "out_protos" "localhost:8787" describe my.custom.server.ServiceCall a method with a JSON body
To send a request, pass the JSON body with -d. All flags must come before the server address and method name. The body is parsed as JSON and sent to the server in protobuf binary format. Use -plaintext for servers without TLS. Servers with TLS work without it, and the README covers TLS options and mutual TLS for servers that require a client certificate.
- Use -d @ to read the request body from stdin, for example from jq output
- With -d @ in Docker, you also need the -i flag
grpcurl -d '{"id": 1234, "tags": ["foo","bar"]}' grpc.server.com:443 my.custom.server.Service/Method
grpcurl -plaintext grpc.server.com:80 my.custom.server.Service/MethodAdd headers and metadata
Add headers or gRPC metadata with -H followed by name:value. Repeat -H for each header.
grpcurl -H header1:value1 -H header2:value2 -d '{"id": 1234, "tags": ["foo","bar"]}' grpc.server.com:443 my.custom.server.Service/MethodWhat people use it for
- Testing a new gRPC endpoint during development before a client is written
- Checking which methods a running gRPC service exposes
- Debugging a service from the terminal by sending a known JSON request
- Calling gRPC methods from shell scripts or pipelines, with request bodies built by jq
- Exporting proto files or a protoset from a server for later use
Frequently asked questions
Is grpcurl free to use?
grpcurl is open source and released under the MIT licence, according to the project. You can use it without a licence fee.
What do I need to use grpcurl?
You need a gRPC server to call, and either server reflection on that server or the proto source or protoset files that define its messages. Install it with Homebrew on macOS, with Docker, or from source with the Go SDK.
How do I install grpcurl on macOS?
Run brew install grpcurl using Homebrew. The project README lists this as the macOS option.
Why does grpcurl say it cannot find the service or message?
Without reflection, grpcurl cannot know the message structure. Supply the proto source files with -import-path and -proto, or a protoset file with -protoset.
Can grpcurl work with plain HTTP REST APIs?
No. grpcurl is specific to gRPC servers. The README notes that regular curl cannot handle the binary protobuf format that gRPC uses.
What are alternatives to grpcurl?
The project lists grpcui, ghz and buf curl as comparable projects. grpcui offers a graphical interface, which grpcurl does not.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
grpcurl is a good choice for backend engineers and developers who need to call gRPC methods from a terminal or script, especially when the server supports reflection. If you need a graphical interface, or your work is only plain HTTP REST, pick a different tool such as grpcui for a visual option.
Install options & downloads