grpcurl

Send an empty request

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

$ grpcurl -H "[Authorization: Bearer $token]" -d '[{"foo": "bar"]}' [grpc.server.com:443] [my.custom.server.Service/Method]

$ grpcurl [grpc.server.com:443] list

$ grpcurl [grpc.server.com:443] list [my.custom.server.Service]

grpcurl [global-flags] [server-addr] [.pkg.Service/Method[=request-data]]
or grpcurl [flags] list|services|methods [service]

-addr string
    gRPC server address (default "localhost:443")

-authority string
    authority header to send

-cacert string
    root CA cert file (PEM)

-cert string
    client cert file (PEM)

-connect-timeout duration
    connect timeout (default 10s)

-d string
    request data (default stdin)

-emit-defaults
    include zero/default field values in output

-failfast
    fail-fast on first error (default unary)

-format string
    output: json|proto|grpcurl (default json)

-H "key:value"
    request header (repeatable)

-help
    show help

-host string
    server host for HTTP/1.1 (default localhost)

-http2-pseudo-header string
    HTTP/2 pseudo-header (e.g. :method)

-import-path string
    proto import paths (comma-separated, repeatable)

-insecure
    skip TLS cert validation

-key string
    client private key (PEM)

-max-msg-send size
    max send msg size (default 4MB)

-max-msg-recv size
    max recv msg size (default 4MB)

-max-time duration
    max RPC duration (default 0s)

-plaintext
    disable TLS

-proto string
    protobuf .proto files (comma-separated)

-protoset string
    FileDescriptorSet file path

-reflect
    use server reflection

-rpclatency
    print RPC latency

-srvcrefs
    print server service refs

-timeout duration
    response msg timeout (default 10s)

-trace
    verbose trace info

-unix string
    Unix socket address

-use-env
    use env vars for address

-v, -verbose
    verbose output

-version
    print version

grpcurl is a command-line tool for interacting with gRPC servers, inspired by curl for HTTP. It allows calling RPC methods (unary, streaming) by specifying protobuf files, protosets, or using server reflection. Supports JSON/proto input/output, TLS/plaintext connections, custom headers, timeouts, and verbose tracing.

Invoke methods directly or use commands like list, services, methods to explore APIs. Ideal for testing, debugging gRPC endpoints from terminal. Written in Go, single static binary, no runtime deps. Handles large messages, Unix sockets, HTTP/2 upgrades. Output formats: JSON (default), proto, grpcurl. Reads request from stdin or -d flag.

Common workflow: load protos, connect to server:port, call ".pkg.Service/Method" with JSON payload.

Requires server reflection or provided .proto files/protosets. Not in standard distros; download binary from GitHub. Streaming RPCs need careful stdin handling. Large protos may slow startup.

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

grpcurl -proto helloworld.proto localhost:50051 list

grpcurl -reflect localhost:8080 helloworld.Greeter/SayHello