grpc-client-cli is a generic gRPC command line client - call any gRPC service. If your service exposes gRPC Reflection service the tool will discover all services and methods automatically. If not, please specify --proto parameter with the path to proto files.
Download the binary and install it to /usr/local directory:
- Linux:
curl -L https://github.com/vadimi/grpc-client-cli/releases/download/v1.24.0/grpc-client-cli_linux_x86_64.tar.gz | tar -C /usr/local/bin -xz(you might need to addsudobefore tar) - macOS:
curl -L https://github.com/vadimi/grpc-client-cli/releases/download/v1.24.0/grpc-client-cli_darwin_x86_64.tar.gz | tar -C /usr/local/bin -xz
For go 1.17+ use this command to install the app to $GOPATH/bin directory:
go install github.com/vadimi/grpc-client-cli/cmd/grpc-client-cli@v1.24.0go install github.com/vadimi/grpc-client-cli/cmd/grpc-client-cli@latest
Just specify a connection string to a service in host:port format and follow instructions to select service, method and enter request message in json or proto text format.
grpc-client-cli localhost:4400 or grpc-client-cli --address localhost:4400
In this case the service needs to expose gRPC Reflection service.
For full list of supported command line args please run grpc-client-cli -h.
To provide the list of services to call specify --proto parameter and --protoimports in case an additional directory for imports is required:
grpc-client-cli --proto /path/to/proto/files localhost:5050
The tool also supports :authority header override.
grpc-client-cli --authority localhost:9090 localhost:5050
It's also possible to capture some of the diagnostic information like request and response sizes, call duration:
grpc-client-cli -V localhost:4400
Proto text format for input and output:
grpc-client-cli --informat text --outformat text localhost:5050
Connect using TLS:
grpc-client-cli --tls localhost:5050
Connect using TLS with a custom CA certificate:
grpc-client-cli --tls --cacert /path/to/ca.crt localhost:5050
Connect using mutual TLS (mTLS):
grpc-client-cli --tls --cert /path/to/client.crt --certkey /path/to/client.key localhost:5050
Skip server certificate verification (testing only):
grpc-client-cli --tls --insecure localhost:5050
Pass extra headers with -H (may be specified multiple times):
grpc-client-cli -H "authorization: Bearer token123" -H "x-request-id: abc" localhost:5050
Set a custom call deadline (default is 15s):
grpc-client-cli --deadline 30s localhost:5050
grpc-client-cli -d 5m localhost:5050
Send keepalive pings with a custom interval:
grpc-client-cli --keepalive --keepalive-time 30s localhost:5050
Override the default 4 MB receive message size limit:
grpc-client-cli --max-receive-message-size 16777216 localhost:5050
By default, response fields are printed using their original proto field names (e.g. user_id, first_name). Use --out-json-names to instead use the json_name option from the proto definition, which typically produces camelCase names (e.g. userId, firstName):
grpc-client-cli --out-json-names localhost:5050
By default v1alpha reflection is used. To let the tool detect the version automatically:
grpc-client-cli --reflect-version auto localhost:5050
To force v1:
grpc-client-cli --reflect-version v1 localhost:5050
grpc-client-cli provides integrated support for services published to a Eureka service registry.
Connecting to a service published to Eureka running on http://localhost:8761/eureka/
grpc-client-cli eureka://application-name/
Connecting to a service running remotely on http://example.com:8761/eureka/
grpc-client-cli eureka://example.com/eureka/application-name/
Connecting to a service running remotely on http://example.com:9000/not-eureka/
grpc-client-cli eureka://example.com:9000/not-eureka/application-name/
The Eureka currently connects to services using the IP Addresses published in the service registry and the following published ports, in order:
- Metadata key "grpc"
- Metadata key "grpc.port"
- Default insecure port
If you require a different default port, please file an issue, and that port will be considered for inclusion.
discover - print service protobuf contract
grpc-client-cli discover localhost:5050
grpc-client-cli -s User discover localhost:5050
health - call health check service, this command returns non-zero exit code in case health check returns NOT_SERVING response or the call fails for any other reason, so it's useful for example in kubernetes health probes
grpc-client-cli health localhost:5050
grpc-client-cli --address localhost:5050 health
In non-interactive mode grpc-client-cli expects all parameters to be passed to execute gRPC service. The address, service and method can also be provided through environment variables: GRPC_CLIENT_CLI_ADDRESS (or GRPC_CLIENT_CLI_ADDR), GRPC_CLIENT_CLI_SERVICE, GRPC_CLIENT_CLI_METHOD.
Pass message json through stdin
echo '{"user_id": "12345"}' | grpc-client-cli -service UserService -method GetUser localhost:5050
cat message.json | grpc-client-cli -service UserService -method GetUser localhost:5050
On windows this could be achieved using type command
type message.json | grpc-client-cli -service UserService -method GetUser localhost:5050
Input file
Another option of providing a file with message json is -input (or -i) parameter:
grpc-client-cli -service UserService -method GetUser -i message.json localhost:5050
To enable autocompletion in your terminal add the following commands to your .bashrc or .zshrc files.
ZSH
PROG=grpc-client-cli
_CLI_ZSH_AUTOCOMPLETE_HACK=1
source autocomplete/zsh_autocomplete
Bash
PROG=grpc-client-cli
source autocomplete/bash_autocomplete
autocomplete directory is located in the root of the repo. Please find more details here.
Most of the fields in proto message can be intuitively mapped to json types. There are some exclusions though:
Timestampmapped to a string inISO 8601format.
For example:
{
"flight_start_date": "2018-03-19T00:00:00.0Z"
}Durationmapped to a string representation in seconds.
For example:
{
"start_time": "72000s",
"some_other_duration": "1s"
}