grpcurl

Like cURL, but for gRPC: Command-line tool for interacting with gRPC servers

10,645

501

10,645

102

View on GitHub

Top Related Projects

grpc-gateway

17,963

gRPC to JSON proxy generator following the gRPC HTTP spec

grpcui

5,133

An interactive web UI for gRPC, along the lines of postman

evans

4,227

Evans: more expressive universal gRPC client

buf

8,842

The best way of working with Protocol Buffers.

protoc-gen-doc

2,620

Documentation generator plugin for Google Protocol Buffers

Quick Overview

grpcurl is a command-line tool that lets you interact with gRPC servers, similar to how curl is used for HTTP requests. It allows you to invoke RPC methods on gRPC servers, making it easier to debug and test gRPC services without writing custom client code.

Pros

Easy-to-use command-line interface for interacting with gRPC servers
Supports both plaintext and TLS connections
Can automatically discover service and method definitions using server reflection
Works with binary and JSON formats for request/response data

Cons

Limited to command-line usage, not suitable for programmatic integration
Requires server reflection to be enabled for full functionality with unknown services
May not support all advanced gRPC features or custom configurations
Learning curve for users unfamiliar with gRPC concepts

Getting Started

To install grpcurl, you can use one of the following methods:

Using Go:

go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest

Using Homebrew (macOS):

brew install grpcurl

Download pre-built binaries from the GitHub releases page.

Basic usage example:

grpcurl -plaintext localhost:8080 list
grpcurl -plaintext -d '{"name": "World"}' localhost:8080 helloworld.Greeter/SayHello

These commands list available services and call a method on a local gRPC server, respectively.

Competitor Comparisons

grpc-gateway

17,963

gRPC to JSON proxy generator following the gRPC HTTP spec

Pros of grpc-gateway

Automatically generates RESTful API from gRPC service definitions
Supports bidirectional streaming and server-side streaming
Integrates well with existing HTTP/REST infrastructure

Cons of grpc-gateway

Requires additional setup and configuration
May introduce performance overhead due to translation layer
Limited flexibility in customizing generated API endpoints

Code Comparison

grpc-gateway:

service YourService {
  rpc GetUser(GetUserRequest) returns (User) {
    option (google.api.http) = {
      get: "/v1/users/{user_id}"
    };
  }
}

grpcurl:

grpcurl -plaintext -d '{"user_id": "123"}' \
  localhost:50051 YourService/GetUser

grpc-gateway focuses on generating RESTful APIs from gRPC services, providing a bridge between gRPC and HTTP/JSON. It's ideal for scenarios where you need to expose gRPC services as REST APIs.

grpcurl, on the other hand, is a command-line tool for interacting with gRPC servers directly. It's useful for testing and debugging gRPC services without the need for custom clients.

While grpc-gateway offers more comprehensive API generation and integration capabilities, grpcurl provides a simpler, more direct approach to interacting with gRPC services, making it easier to use for quick testing and exploration.

grpcui

5,133

An interactive web UI for gRPC, along the lines of postman

Pros of grpcui

Provides a user-friendly web interface for interacting with gRPC services
Allows for easy exploration and testing of gRPC methods without writing code
Supports automatic form generation based on protobuf message definitions

Cons of grpcui

Requires a web browser and may not be suitable for all environments
Has a larger footprint and more dependencies compared to grpcurl
May have a steeper learning curve for users unfamiliar with web interfaces

Code Comparison

grpcui:

import (
    "github.com/fullstorydev/grpcui/standalone"
    "google.golang.org/grpc"
)

handler, err := standalone.HandlerViaReflection(ctx, cc, target)

grpcurl:

import (
    "github.com/fullstorydev/grpcurl"
    "google.golang.org/grpc"
)

err := grpcurl.InvokeRPC(ctx, descSource, cc, method, headers, handler, msg)

Both repositories provide tools for interacting with gRPC services, but they serve different use cases. grpcui offers a graphical interface for easier exploration and testing, while grpcurl provides a command-line tool for more streamlined and scriptable interactions. The choice between the two depends on the specific needs of the user and the environment in which they are working.

evans

4,227

Evans: more expressive universal gRPC client

Pros of Evans

Interactive CLI with a REPL interface for easier exploration and testing of gRPC services
Supports both CLI and TUI modes, offering flexibility in usage
Built-in code completion and syntax highlighting for improved user experience

Cons of Evans

Less widespread adoption compared to gRPCurl
May have a steeper learning curve for users familiar with curl-like tools
Fewer options for output formatting

Code Comparison

Evans:

evans -r repl

> call SayHello

gRPCurl:

grpcurl -d '{"name": "World"}' \
    localhost:50051 helloworld.Greeter/SayHello

Evans provides an interactive REPL environment, while gRPCurl uses a more traditional command-line approach similar to curl. Evans allows for exploration and multiple calls within a single session, whereas gRPCurl is designed for single, specific requests.

Both tools serve similar purposes but cater to different user preferences and use cases. Evans is more suited for interactive debugging and exploration, while gRPCurl excels in scripting and automation scenarios. The choice between the two depends on the specific requirements of the user and their familiarity with different interface styles.

buf

8,842

The best way of working with Protocol Buffers.

Pros of buf

Comprehensive toolset for Protocol Buffers and gRPC development, including linting, breaking change detection, and code generation
Supports modern Protobuf features and best practices out of the box
Offers a more streamlined workflow for managing Protobuf schemas across projects

Cons of buf

Steeper learning curve due to its broader feature set
May be overkill for simple gRPC testing scenarios
Requires additional setup and configuration compared to grpcurl

Code comparison

grpcurl:

grpcurl -plaintext localhost:8080 list
grpcurl -plaintext -d '{"name": "World"}' localhost:8080 helloworld.Greeter/SayHello

buf:

buf lint
buf breaking --against '.git#branch=main'
buf generate

Summary

grpcurl is a lightweight CLI tool focused on interacting with gRPC servers, making it ideal for quick testing and debugging. buf, on the other hand, is a more comprehensive solution for managing Protocol Buffers and gRPC projects, offering features like linting, breaking change detection, and code generation. While buf provides a more robust development experience, it may be more complex for simple use cases where grpcurl's straightforward approach is sufficient.

protoc-gen-doc

2,620

Documentation generator plugin for Google Protocol Buffers

Pros of protoc-gen-doc

Generates comprehensive documentation for Protocol Buffers
Supports multiple output formats (HTML, Markdown, JSON)
Customizable templates for tailored documentation

Cons of protoc-gen-doc

Limited to Protocol Buffers documentation generation
Requires separate installation and setup
No direct gRPC interaction capabilities

Code Comparison

protoc-gen-doc:

protoc --doc_out=./docs --doc_opt=html,index.html myproto.proto

grpcurl:

grpcurl -proto myproto.proto -plaintext localhost:8080 list

Key Differences

protoc-gen-doc is focused on generating documentation for Protocol Buffers, while grpcurl is a command-line tool for interacting with gRPC servers. protoc-gen-doc excels in creating readable and customizable documentation, whereas grpcurl provides functionality for testing and debugging gRPC services.

protoc-gen-doc is ideal for teams needing to generate and maintain API documentation, especially when working with Protocol Buffers. grpcurl, on the other hand, is more suitable for developers who need to interact with gRPC services directly, test endpoints, and debug API calls.

While both tools work with Protocol Buffers, they serve different purposes in the gRPC ecosystem. protoc-gen-doc enhances documentation workflows, while grpcurl facilitates direct interaction with gRPC services.

grpc-web

8,558

gRPC for Web Clients

Pros of grpc-web

Enables gRPC communication directly from web browsers
Supports both HTTP/1.1 and HTTP/2 protocols
Provides automatic code generation for client-side stubs

Cons of grpc-web

Limited to unary and server streaming RPCs (no client streaming or bidirectional streaming)
Requires a proxy for browser-to-server communication
More complex setup compared to simple HTTP requests

Code Comparison

grpc-web client-side code:

const { HelloRequest, HelloReply } = require('./helloworld_pb.js');
const { GreeterClient } = require('./helloworld_grpc_web_pb.js');

var client = new GreeterClient('http://localhost:8080');

var request = new HelloRequest();
request.setName('World');

client.sayHello(request, {}, (err, response) => {
  console.log(response.getMessage());
});

grpcurl command-line usage:

grpcurl -plaintext -d '{"name": "World"}' \
    localhost:8080 helloworld.Greeter/SayHello

Summary

grpc-web is designed for web browser-to-server gRPC communication, offering seamless integration with web applications. It provides automatic code generation and supports both HTTP/1.1 and HTTP/2. However, it has limitations in streaming capabilities and requires a proxy. grpcurl, on the other hand, is a command-line tool for interacting with gRPC servers, offering simplicity and ease of use for testing and debugging purposes.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

gRPCurl

grpcurl is a command-line tool that lets you interact with gRPC servers. It's basically curl for gRPC servers.

The main purpose for this tool is to invoke RPC methods on a gRPC server from the command-line. gRPC servers use a binary encoding on the wire (protocol buffers, or "protobufs" for short). So they are basically impossible to interact with using regular curl (and older versions of curl that do not support HTTP/2 are of course non-starters). This program accepts messages using JSON encoding, which is much more friendly for both humans and scripts.

With this tool you can also browse the schema for gRPC services, either by querying a server that supports server reflection, by reading proto source files, or by loading in compiled "protoset" files (files that contain encoded file descriptor protos). In fact, the way the tool transforms JSON request data into a binary encoded protobuf is using that very same schema. So, if the server you interact with does not support reflection, you will either need the proto source files that define the service or need protoset files that grpcurl can use.

This repo also provides a library package, github.com/fullstorydev/grpcurl, that has functions for simplifying the construction of other command-line tools that dynamically invoke gRPC endpoints. This code is a great example of how to use the various packages of the protoreflect library, and shows off what they can do.

See also the grpcurl talk at GopherCon 2018.

Features

grpcurl supports all kinds of RPC methods, including streaming methods. You can even operate bi-directional streaming methods interactively by running grpcurl from an interactive terminal and using stdin as the request body!

grpcurl supports both secure/TLS servers and plain-text servers (i.e. no TLS) and has numerous options for TLS configuration. It also supports mutual TLS, where the client is required to present a client certificate.

As mentioned above, grpcurl works seamlessly if the server supports the reflection service. If not, you can supply the .proto source files or you can supply protoset files (containing compiled descriptors, produced by protoc) to grpcurl.

Installation

Binaries

Download the binary from the releases page.

Homebrew (macOS)

On macOS, grpcurl is available via Homebrew:

brew install grpcurl

Docker

For platforms that support Docker, you can download an image that lets you run grpcurl:

# Download image
docker pull fullstorydev/grpcurl:latest
# Run the tool
docker run fullstorydev/grpcurl api.grpc.me:443 list

Note that there are some pitfalls when using docker:

If you need to interact with a server listening on the host's loopback network, you must specify the host as host.docker.internal instead of localhost (for Mac or Windows) OR have the container use the host network with -network="host" (Linux only).
If you need to provide proto source files or descriptor sets, you must mount the folder containing the files as a volume (-v $(pwd):/protos) and adjust the import paths to container paths accordingly.
If you want to provide the request message via stdin, using the -d @ option, you need to use the -i flag on the docker command.

Other Packages

There are numerous other ways to install grpcurl, thanks to support from third parties that have created recipes/packages for it. These include other ways to install grpcurl on a variety of environments, including Windows and myriad Linux distributions.

You can see more details and the full list of other packages for grpcurl at repology.org: https://repology.org/project/grpcurl/information

From Source

If you already have the Go SDK installed, you can use the go tool to install grpcurl:

go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest

This installs the command into the bin sub-folder of wherever your $GOPATH environment variable points. (If you have no GOPATH environment variable set, the default install location is $HOME/go/bin). If this directory is already in your $PATH, then you should be good to go.

If you have already pulled down this repo to a location that is not in your $GOPATH and want to build from the sources, you can cd into the repo and then run make install.

If you encounter compile errors and are using a version of the Go SDK older than 1.13, you could have out-dated versions of grpcurl's dependencies. You can update the dependencies by running make updatedeps. Or, if you are using Go 1.11 or 1.12, you can add GO111MODULE=on as a prefix to the commands above, which will also build using the right versions of dependencies (vs. whatever you may already have in your GOPATH).

Usage

The usage doc for the tool explains the numerous options:

grpcurl -help

In the sections below, you will find numerous examples demonstrating how to use grpcurl.

Invoking RPCs

Invoking an RPC on a trusted server (e.g. TLS without self-signed key or custom CA) that requires no client certs and supports server reflection is the simplest thing to do with grpcurl. This minimal invocation sends an empty request body:

grpcurl grpc.server.com:443 my.custom.server.Service/Method

# no TLS
grpcurl -plaintext grpc.server.com:80 my.custom.server.Service/Method

To send a non-empty request, use the -d argument. Note that all arguments must come before the server address and method name:

grpcurl -d '{"id": 1234, "tags": ["foo","bar"]}' \
    grpc.server.com:443 my.custom.server.Service/Method

As can be seen in the example, the supplied body must be in JSON format. The body will be parsed and then transmitted to the server in the protobuf binary format.

If you want to include grpcurl in a command pipeline, such as when using jq to create a request body, you can use -d @, which tells grpcurl to read the actual request body from stdin:

grpcurl -d @ grpc.server.com:443 my.custom.server.Service/Method <<EOM
{
  "id": 1234,
  "tags": [
    "foor",
    "bar"
  ]
}
EOM

Listing Services

To list all services exposed by a server, use the "list" verb. When using .proto source or protoset files instead of server reflection, this lists all services defined in the source or protoset files.

# 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

# Export proto files (use -proto-out-dir to specify the output directory)
grpcurl -plaintext -proto-out-dir "out_protos" "localhost:8787" describe my.custom.server.Service

# Export protoset file (use -protoset-out to specify the output file)
grpcurl -plaintext -protoset-out "out.protoset" "localhost:8787" describe my.custom.server.Service

The "list" verb also lets you see all methods in a particular service:

grpcurl localhost:8787 list my.custom.server.Service

Describing Elements

The "describe" verb will print the type of any symbol that the server knows about or that is found in a given protoset file. It also prints a description of that symbol, in the form of snippets of proto source. It won't necessarily be the original source that defined the element, but it will be equivalent.

# Server supports reflection
grpcurl localhost:8787 describe my.custom.server.Service.MethodOne

# Using compiled protoset files
grpcurl -protoset my-protos.bin describe my.custom.server.Service.MethodOne

# Using proto sources
grpcurl -import-path ../protos -proto my-stuff.proto describe my.custom.server.Service.MethodOne

Descriptor Sources

The grpcurl tool can operate on a variety of sources for descriptors. The descriptors are required, in order for grpcurl to understand the RPC schema, translate inputs into the protobuf binary format as well as translate responses from the binary format into text. The sections below document the supported sources and what command-line flags are needed to use them.

Server Reflection

Without any additional command-line flags, grpcurl will try to use server reflection.

Examples for how to set up server reflection can be found here.

When using reflection, the server address (host:port or path to Unix socket) is required even for "list" and "describe" operations, so that grpcurl can connect to the server and ask it for its descriptors.

Proto Source Files

To use grpcurl on servers that do not support reflection, you can use .proto source files.

In addition to using -proto flags to point grpcurl at the relevant proto source file(s), you may also need to supply -import-path flags to tell grpcurl the folders from which dependencies can be imported.

Just like when compiling with protoc, you do not need to provide an import path for the location of the standard protos included with protoc (which contain various "well-known types" with a package definition of google.protobuf). These files are "known" by grpcurl as a snapshot of their descriptors is built into the grpcurl binary.

When using proto sources, you can omit the server address (host:port or path to Unix socket) when using the "list" and "describe" operations since they only need to consult the proto source files.

Protoset Files

You can also use compiled protoset files with grpcurl. If you are scripting grpcurl and need to re-use the same proto sources for many invocations, you will see better performance by using protoset files (since it skips the parsing and compilation steps with each invocation).

Protoset files contain binary encoded google.protobuf.FileDescriptorSet protos. To create a protoset file, invoke protoc with the *.proto files that define the service:

protoc --proto_path=. \
    --descriptor_set_out=myservice.protoset \
    --include_imports \
    my/custom/server/service.proto

The --descriptor_set_out argument is what tells protoc to produce a protoset, and the --include_imports argument is necessary for the protoset to contain everything that grpcurl needs to process and understand the schema.

When using protosets, you can omit the server address (host:port or path to Unix socket) when using the "list" and "describe" operations since they only need to consult the protoset files.

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot