{"id":13416699,"url":"https://github.com/fullstorydev/grpcurl","last_synced_at":"2025-09-09T20:25:42.905Z","repository":{"id":37359419,"uuid":"111431261","full_name":"fullstorydev/grpcurl","owner":"fullstorydev","description":"Like cURL, but for gRPC: Command-line tool for interacting with gRPC servers","archived":false,"fork":false,"pushed_at":"2025-04-17T00:05:25.000Z","size":636,"stargazers_count":11492,"open_issues_count":106,"forks_count":532,"subscribers_count":78,"default_branch":"master","last_synced_at":"2025-04-24T00:37:54.511Z","etag":null,"topics":["golang","grpc","protobuf"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fullstorydev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-11-20T15:53:31.000Z","updated_at":"2025-04-23T22:52:42.000Z","dependencies_parsed_at":"2023-10-04T06:06:54.778Z","dependency_job_id":"ff6a6f09-da4f-4f60-b43d-f1b8db75aa36","html_url":"https://github.com/fullstorydev/grpcurl","commit_stats":{"total_commits":205,"total_committers":57,"mean_commits":"3.5964912280701755","dds":0.5219512195121951,"last_synced_commit":"56181ba330d65224a36235c4cd7e8ad3821dc439"},"previous_names":["fullstoryeng/grpcurl"],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullstorydev%2Fgrpcurl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullstorydev%2Fgrpcurl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullstorydev%2Fgrpcurl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullstorydev%2Fgrpcurl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fullstorydev","download_url":"https://codeload.github.com/fullstorydev/grpcurl/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252525453,"owners_count":21762298,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["golang","grpc","protobuf"],"created_at":"2024-07-30T22:00:20.348Z","updated_at":"2025-05-05T15:43:38.496Z","avatar_url":"https://github.com/fullstorydev.png","language":"Go","readme":"# gRPCurl\n[![Build Status](https://circleci.com/gh/fullstorydev/grpcurl/tree/master.svg?style=svg)](https://circleci.com/gh/fullstorydev/grpcurl/tree/master)\n[![Go Report Card](https://goreportcard.com/badge/github.com/fullstorydev/grpcurl)](https://goreportcard.com/report/github.com/fullstorydev/grpcurl)\n[![Snap Release Status](https://snapcraft.io/grpcurl/badge.svg)](https://snapcraft.io/grpcurl)\n\n`grpcurl` is a command-line tool that lets you interact with gRPC servers. It's\nbasically `curl` for gRPC servers.\n\nThe main purpose for this tool is to invoke RPC methods on a gRPC server from the\ncommand-line. gRPC servers use a binary encoding on the wire\n([protocol buffers](https://developers.google.com/protocol-buffers/), or \"protobufs\"\nfor short). So they are basically impossible to interact with using regular `curl`\n(and older versions of `curl` that do not support HTTP/2 are of course non-starters).\nThis program accepts messages using JSON encoding, which is much more friendly for both\nhumans and scripts.\n\nWith this tool you can also browse the schema for gRPC services, either by querying\na server that supports [server reflection](https://github.com/grpc/grpc/blob/master/src/proto/grpc/reflection/v1/reflection.proto),\nby reading proto source files, or by loading in compiled \"protoset\" files (files that contain\nencoded file [descriptor protos](https://github.com/google/protobuf/blob/master/src/google/protobuf/descriptor.proto)).\nIn fact, the way the tool transforms JSON request data into a binary encoded protobuf\nis using that very same schema. So, if the server you interact with does not support\nreflection, you will either need the proto source files that define the service or need\nprotoset files that `grpcurl` can use.\n\nThis repo also provides a library package, `github.com/fullstorydev/grpcurl`, that has\nfunctions for simplifying the construction of other command-line tools that dynamically\ninvoke gRPC endpoints. This code is a great example of how to use the various packages of\nthe [protoreflect](https://godoc.org/github.com/jhump/protoreflect) library, and shows\noff what they can do.\n\nSee also the [`grpcurl` talk at GopherCon 2018](https://www.youtube.com/watch?v=dDr-8kbMnaw).\n\n## Features\n`grpcurl` supports all kinds of RPC methods, including streaming methods. You can even\noperate bi-directional streaming methods interactively by running `grpcurl` from an\ninteractive terminal and using stdin as the request body!\n\n`grpcurl` supports both secure/TLS servers _and_ plain-text servers (i.e. no TLS) and has\nnumerous options for TLS configuration. It also supports mutual TLS, where the client is\nrequired to present a client certificate.\n\nAs mentioned above, `grpcurl` works seamlessly if the server supports the reflection\nservice. If not, you can supply the `.proto` source files or you can supply protoset\nfiles (containing compiled descriptors, produced by `protoc`) to `grpcurl`.\n\n## Installation\n\n### Binaries\n\nDownload the binary from the [releases](https://github.com/fullstorydev/grpcurl/releases) page.\n\n### Homebrew (macOS)\n\nOn macOS, `grpcurl` is available via Homebrew:\n```shell\nbrew install grpcurl\n```\n\n### Docker\n\nFor platforms that support Docker, you can download an image that lets you run `grpcurl`:\n```shell\n# Download image\ndocker pull fullstorydev/grpcurl:latest\n# Run the tool\ndocker run fullstorydev/grpcurl api.grpc.me:443 list\n```\nNote that there are some pitfalls when using docker:\n- 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).\n- 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.\n- 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.\n\n### Other Packages\n\nThere are numerous other ways to install `grpcurl`, thanks to support from third parties that\nhave created recipes/packages for it. These include other ways to install `grpcurl` on a variety\nof environments, including Windows and myriad Linux distributions.\n\nYou can see more details and the full list of other packages for `grpcurl` at _repology.org_:\nhttps://repology.org/project/grpcurl/information\n\n### Snap\n\nYou can install `grpcurl` using the snap package:\n\n`snap install grpcurl`\n\n### From Source\nIf you already have the [Go SDK](https://golang.org/doc/install) installed, you can use the `go`\ntool to install `grpcurl`:\n```shell\ngo install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest\n```\n\nThis installs the command into the `bin` sub-folder of wherever your `$GOPATH`\nenvironment variable points. (If you have no `GOPATH` environment variable set,\nthe default install location is `$HOME/go/bin`). If this directory is already in\nyour `$PATH`, then you should be good to go.\n\nIf you have already pulled down this repo to a location that is not in your\n`$GOPATH` and want to build from the sources, you can `cd` into the repo and then\nrun `make install`.\n\nIf you encounter compile errors and are using a version of the Go SDK older than 1.13,\nyou could have out-dated versions of `grpcurl`'s dependencies. You can update the\ndependencies by running `make updatedeps`. Or, if you are using Go 1.11 or 1.12, you\ncan add `GO111MODULE=on` as a prefix to the commands above, which will also build using\nthe right versions of dependencies (vs. whatever you may already have in your `GOPATH`).\n\n## Usage\nThe usage doc for the tool explains the numerous options:\n```shell\ngrpcurl -help\n```\n\nIn the sections below, you will find numerous examples demonstrating how to use\n`grpcurl`.\n\n### Invoking RPCs\nInvoking an RPC on a trusted server (e.g. TLS without self-signed key or custom CA)\nthat requires no client certs and supports server reflection is the simplest thing to\ndo with `grpcurl`. This minimal invocation sends an empty request body:\n```shell\ngrpcurl grpc.server.com:443 my.custom.server.Service/Method\n\n# no TLS\ngrpcurl -plaintext grpc.server.com:80 my.custom.server.Service/Method\n```\n\nTo send a non-empty request, use the `-d` argument. Note that all arguments must come\n*before* the server address and method name:\n```shell\ngrpcurl -d '{\"id\": 1234, \"tags\": [\"foo\",\"bar\"]}' \\\n    grpc.server.com:443 my.custom.server.Service/Method\n```\n\nAs can be seen in the example, the supplied body must be in JSON format. The body will\nbe parsed and then transmitted to the server in the protobuf binary format.\n\nIf you want to include `grpcurl` in a command pipeline, such as when using `jq` to\ncreate a request body, you can use `-d @`, which tells `grpcurl` to read the actual\nrequest body from stdin:\n```shell\ngrpcurl -d @ grpc.server.com:443 my.custom.server.Service/Method \u003c\u003cEOM\n{\n  \"id\": 1234,\n  \"tags\": [\n    \"foor\",\n    \"bar\"\n  ]\n}\nEOM\n```\n### Adding Headers/Metadata to Request\nAdding of headers / metadata to a rpc request is possible via the `-H name:value` command line option. Multiple headers can be added in a similar fashion.\nExample :\n```shell\ngrpcurl -H header1:value1 -H header2:value2 -d '{\"id\": 1234, \"tags\": [\"foo\",\"bar\"]}' grpc.server.com:443 my.custom.server.Service/Method\n```\nFor more usage guide, check out the help docs via `grpcurl -help`\n\n### Listing Services\nTo list all services exposed by a server, use the \"list\" verb. When using `.proto` source\nor protoset files instead of server reflection, this lists all services defined in the\nsource or protoset files.\n```shell\n# Server supports reflection\ngrpcurl localhost:8787 list\n\n# Using compiled protoset files\ngrpcurl -protoset my-protos.bin list\n\n# Using proto sources\ngrpcurl -import-path ../protos -proto my-stuff.proto list\n\n# Export proto files (use -proto-out-dir to specify the output directory)\ngrpcurl -plaintext -proto-out-dir \"out_protos\" \"localhost:8787\" describe my.custom.server.Service\n\n# Export protoset file (use -protoset-out to specify the output file)\ngrpcurl -plaintext -protoset-out \"out.protoset\" \"localhost:8787\" describe my.custom.server.Service\n\n```\n\nThe \"list\" verb also lets you see all methods in a particular service:\n```shell\ngrpcurl localhost:8787 list my.custom.server.Service\n```\n\n### Describing Elements\nThe \"describe\" verb will print the type of any symbol that the server knows about\nor that is found in a given protoset file. It also prints a description of that\nsymbol, in the form of snippets of proto source. It won't necessarily be the\noriginal source that defined the element, but it will be equivalent.\n\n```shell\n# Server supports reflection\ngrpcurl localhost:8787 describe my.custom.server.Service.MethodOne\n\n# Using compiled protoset files\ngrpcurl -protoset my-protos.bin describe my.custom.server.Service.MethodOne\n\n# Using proto sources\ngrpcurl -import-path ../protos -proto my-stuff.proto describe my.custom.server.Service.MethodOne\n```\n\n## Descriptor Sources\nThe `grpcurl` tool can operate on a variety of sources for descriptors. The descriptors\nare required, in order for `grpcurl` to understand the RPC schema, translate inputs\ninto the protobuf binary format as well as translate responses from the binary format\ninto text. The sections below document the supported sources and what command-line flags\nare needed to use them.\n\n### Server Reflection\n\nWithout any additional command-line flags, `grpcurl` will try to use [server reflection](https://github.com/grpc/grpc/blob/master/src/proto/grpc/reflection/v1/reflection.proto).\n\nExamples for how to set up server reflection can be found [here](https://github.com/grpc/grpc/blob/master/doc/server-reflection.md#known-implementations).\n\nWhen using reflection, the server address (host:port or path to Unix socket) is required\neven for \"list\" and \"describe\" operations, so that `grpcurl` can connect to the server\nand ask it for its descriptors.\n\n### Proto Source Files\nTo use `grpcurl` on servers that do not support reflection, you can use `.proto` source\nfiles.\n\nIn addition to using `-proto` flags to point `grpcurl` at the relevant proto source file(s),\nyou may also need to supply `-import-path` flags to tell `grpcurl` the folders from which\ndependencies can be imported.\n\nJust like when compiling with `protoc`, you do *not* need to provide an import path for the\nlocation of the standard protos included with `protoc` (which contain various \"well-known\ntypes\" with a package definition of `google.protobuf`). These files are \"known\" by `grpcurl`\nas a snapshot of their descriptors is built into the `grpcurl` binary.\n\nWhen using proto sources, you can omit the server address (host:port or path to Unix socket)\nwhen using the \"list\" and \"describe\" operations since they only need to consult the proto\nsource files.\n\n### Protoset Files\nYou can also use compiled protoset files with `grpcurl`. If you are scripting `grpcurl` and\nneed to re-use the same proto sources for many invocations, you will see better performance\nby using protoset files (since it skips the parsing and compilation steps with each\ninvocation).\n\nProtoset files contain binary encoded `google.protobuf.FileDescriptorSet` protos. To create\na protoset file, invoke `protoc` with the `*.proto` files that define the service:\n```shell\nprotoc --proto_path=. \\\n    --descriptor_set_out=myservice.protoset \\\n    --include_imports \\\n    my/custom/server/service.proto\n```\n\nThe `--descriptor_set_out` argument is what tells `protoc` to produce a protoset,\nand the `--include_imports` argument is necessary for the protoset to contain\neverything that `grpcurl` needs to process and understand the schema.\n\nWhen using protosets, you can omit the server address (host:port or path to Unix socket)\nwhen using the \"list\" and \"describe\" operations since they only need to consult the\nprotoset files.\n\n","funding_links":[],"categories":["Popular","HarmonyOS","Go","开源类库","Projects","Go (134)","golang","Open source library","Tools","HTTP/HTTPS/gRPC","Specialized API Clients (GraphQL, gRPC, WebSocket)","Awesome Tools","RPC","Identifiers","CLI"],"sub_categories":["Windows Manager","RPC","API Testing","CLI","gRPC Tools","60. [grpcurl](https://github.com/fullstorydev/grpcurl)","Terminal Tools","GUI - other"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffullstorydev%2Fgrpcurl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffullstorydev%2Fgrpcurl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffullstorydev%2Fgrpcurl/lists"}