Skip to content
grpcmd
Docs Blog

Frequently Asked Questions

Proto Files

If you want to use .proto files instead of Reflection, you can pass one or more comma-separated file locations to the --protos (shorthand: -p) flag. For example:

grpc --protos a.proto --protos b.proto,c.proto :50051

Proto Import Paths

If your .proto files contain import statements, you’ll likely want to set the search paths for the imports to work properly. To do this, you can pass one or more comma-separated directory locations to the --paths (shorthand: -P) flag. For example:

grpc --protos a.proto --paths ../protos/ :50051

Sending an Empty Request

To send an empty request, simply pass an empty argument for the request data. For example:

grpc :50051 UnaryMethod {}

Sending Additional Request Headers (Metadata)

To send a request with additional headers, simply pass one or more key: value arguments before the request data. For example:

grpc :50051 UnaryMethod 'custom-header: custom-value' {}

or

grpc :50051 UnaryMethod header-1:value-1 header-2:value-2 {}

Exit Codes

On success, the exit code will be 0. However, if there is a non-OK gRPC status code in the response, the exit code will be equal to 64 + the gRPC status code. Other application errors will have exit codes less than 64. For example, failure to connect to the provided address will result in an exit code of 1.

Disambiguating Short Method Names

grpcmd supports taking in short methods names instead of requiring fully-qualified and namespaced method names. In the case where a short method name exists in more that one namespace or package, the tool will throw an error. For example:

grpc :50051 ServerReflectionInfo

Output:

Error while describing method ServerReflectionInfo:
    Ambiguous method ServerReflectionInfo. Matching methods:
            grpc.reflection.v1.ServerReflection.ServerReflectionInfo
            grpc.reflection.v1alpha.ServerReflection.ServerReflectionInfo

Stop Firewall Popup

You may receive a firewall popup when running grpc server :50051. For example, this is the case on macOS. The reason for this is that the address :50051 will listen to port 50051 on all network interfaces. To solve this, you can specify the loopback interface in the address. For example:

  • grpc server localhost:50051
  • grpc server 127.0.0.1:50051

When connecting to the server, you can still start with grpc :50051 if you prefer.

Setup Shell Completion

Homebrew

If you installed the grpcmd package using Homebrew, the shell completion scripts should be installed to their respective directories. If you haven’t setup brew completions, follow this guide. The guide includes directions for bash, zsh, and fish.

Manual

If you want to manually enable shell completion, run the following commands based on your shell. Note: Running the following commands will only affect the current session.

Bash

source <(grpc completion bash)

Zsh

source <(grpc completion zsh)

fish

grpc completion fish | source

PowerShell

bash completion powershell | Out-String | Invoke-Expression