grpcurl

Visit Website

Introduction

grpcurl is a command-line tool that lets you interact with gRPC servers. gRPC uses a binary encoding (protocol buffers) over HTTP/2, so plain curl cannot talk to it. grpcurl accepts and prints messages as JSON, which makes gRPC calls as easy to script as REST calls.

To know what a server offers, grpcurl uses gRPC server reflection when the server supports it, or reads proto source files or compiled protoset files. grpcurl -plaintext localhost:50051 list lists services, describe shows methods and message types, and a call is as simple as passing JSON with -d and the fully qualified method name.

It supports unary and streaming RPCs, TLS and mutual TLS, plaintext connections for local development, request headers and metadata with -H, and reading request data from standard input. Because output is JSON, it pipes cleanly into jq for assertions in shell scripts and CI smoke checks.

grpcurl is maintained by FullStory, has about 12,900 GitHub stars and released v1.9.4 in August 2026, with commits continuing in November 2026. It is available through Homebrew, Docker, Go install and release binaries, and has a sibling project, grpcui, for a browser-based interface.

In the quality loop, grpcurl is a debugging and smoke-testing tool at the API and integration stages. It is often the first thing engineers reach for when a gRPC service misbehaves, and it is handy for health checks after deployment. For full test suites, teams usually pair it with language-level tests or tools such as Karate, and ghz for load.

Because it is a single static binary with no runtime dependencies, grpcurl is also easy to bake into container images used for debugging inside Kubernetes clusters, where many gRPC services are only reachable internally.

The source code is at fullstorydev/grpcurl on GitHub under the MIT licence, with about 12,900 stars; the most recent commit was on 2 November 2026.

grpcurl is most valuable during development and incident response, when someone needs to call a gRPC method quickly without writing a client. Enabling server reflection in non-production environments makes this much easier, because grpcurl can list services and describe messages without local proto files; where reflection is disabled for security, keep the proto files or a compiled descriptor set available to the team. For repeatable checks, wrap grpcurl calls in small scripts and assert on the JSON output, but move to a proper test framework once the number of cases grows.

Features

1. JSON in and out: Write requests and read responses as JSON.
2. Server reflection: Discover services without local proto files.
3. Proto and protoset files: Work with servers that do not expose reflection.
4. List and describe: Browse services, methods and message types.
5. Streaming: Client, server and bidirectional streaming calls.
6. TLS and mTLS: Secure connections, or -plaintext for local servers.
7. Headers and metadata: Send auth tokens and custom metadata.
8. Stdin input: Pipe request data from files or scripts.
9. Scriptable: Combine with jq and shell for checks.
10. Many install options: Homebrew, Docker, Go and binaries.

Pros

1. Indispensable for gRPC debugging: The standard CLI for gRPC.
2. Easy in CI: Simple health and smoke checks.
3. Free to use: Open source under the MIT licence, so the core tool costs nothing to use.
4. Actively maintained: The repository had commits as recent as 2 November 2026.
5. Community: About 12,900 GitHub stars.

Cons

1. No assertions: Pair with jq or a test framework to check results.
2. CLI only: Use grpcui or a desktop client for interactive exploration.
3. Reflection dependency: Without reflection you must supply proto files.

Usage and Links (Example)

List services and call a method on a local server with reflection enabled:

grpcurl -plaintext localhost:50051 list
grpcurl -plaintext -d '{"id": "42"}' localhost:50051 shop.v1.OrderService/GetOrder

A simple CI smoke check with jq:

grpcurl -plaintext -d '{}' api:50051 grpc.health.v1.Health/Check | jq -e '.status == "SERVING"'

Practical tips:

1. Enable server reflection in non-production environments to make debugging easier.
2. Use -H 'authorization: Bearer ...' for authenticated calls.
3. Keep common calls in a script so the team shares the same smoke checks.

Resources:

• grpcurl website

Pricing

grpcurl is free and open source under the MIT licence.

Recommended for?

1. Anyone building or operating gRPC services.
2. CI smoke and health checks for gRPC endpoints.
3. Not a fit as a full test framework on its own.

Conclusion

grpcurl is the essential command-line tool for gRPC: simple, scriptable and actively maintained.

Every team running gRPC should have it in their toolbox, alongside proper automated tests.

On CheckOps, grpcurl is filed under the API & contract testing and Integration testing stages. Related tools listed here include grpcui, Kreya, ghz, Postman, Insomnia and Karate. Before choosing, compare them on licence, supported languages and platforms, hosting model, and how well each fits your existing CI pipeline. Facts on this page were checked against the official website, documentation and repository on 11 November 2026; statements the vendor makes about its own product are marked as vendor claims.