1# gRPC command line tool 2 3## Overview 4 5This document describes the command line tool that comes with gRPC repository. 6It is desirable to have command line tools written in other languages roughly 7follow the same syntax and flags. 8 9> [!NOTE] 10> At present, the tool needs to be built from source, and it should be moved out 11> to grpc-tools repository as a stand alone application once it is mature 12> enough. This tool in its current state though is not up to par in its 13> user-friendliness. Other tools in the ecosystem, for example, 14> [grpcurl](https://github.com/fullstorydev/grpcurl) are better maintained. 15 16## Core functionality 17 18The command line tool can do the following things: 19 20- Send unary rpc. 21- Attach metadata and display received metadata. 22- Handle common authentication to server. 23- Infer request/response types from server reflection result. 24- Find the request/response types from a given proto file. 25- Read proto request in text form. 26- Read request in wire form (for protobuf messages, this means serialized 27 binary form). 28- Display proto response in text form. 29- Write response in wire form to a file. 30 31The command line tool should support the following things: 32 33- List server services and methods through server reflection. 34- Fine-grained auth control (such as, use this oauth token to talk to the 35 server). 36- Send streaming rpc. 37 38## Code location 39 40To use the tool, you need to get the grpc repository and make sure your system 41has the prerequisites for building grpc from source, given in the 42[installation instructions](../BUILDING.md). 43 44In order to build the grpc command line tool from a fresh clone of the grpc 45repository, you need to run the following command to update submodules: 46 47``` 48git submodule update --init 49``` 50 51Once the prerequisites are satisfied, you can build with cmake: 52 53``` 54$ mkdir -p cmake/build 55$ cd cmake/build 56$ cmake -DgRPC_BUILD_TESTS=ON ../.. 57$ make grpc_cli 58``` 59 60The main file can be found at 61https://github.com/grpc/grpc/blob/master/test/cpp/util/grpc_cli.cc 62 63## Prerequisites 64 65Most `grpc_cli` commands need the server to support server reflection. See 66guides for 67[Java](https://github.com/grpc/grpc-java/blob/master/documentation/server-reflection-tutorial.md#enable-server-reflection) 68, 69[C++](https://github.com/grpc/grpc/blob/master/doc/server_reflection_tutorial.md) 70and 71[Go](https://github.com/grpc/grpc-go/blob/master/Documentation/server-reflection-tutorial.md) 72 73Local proto files can be used as an alternative. See instructions 74[below](#Call-a-remote-method). 75 76## Usage 77 78### List services 79 80`grpc_cli ls` command lists services and methods exposed at a given port 81 82- List all the services exposed at a given port 83 84 ```sh 85 $ grpc_cli ls localhost:50051 86 ``` 87 88 output: 89 90 ```none 91 helloworld.Greeter 92 grpc.reflection.v1alpha.ServerReflection 93 ``` 94 95 The `localhost:50051` part indicates the server you are connecting to. 96 97- List one service with details 98 99 `grpc_cli ls` command inspects a service given its full name (in the format 100 of \<package\>.\<service\>). It can print information with a long listing 101 format when `-l` flag is set. This flag can be used to get more details 102 about a service. 103 104 ```sh 105 $ grpc_cli ls localhost:50051 helloworld.Greeter -l 106 ``` 107 108 `helloworld.Greeter` is full name of the service. 109 110 output: 111 112 ```proto 113 filename: helloworld.proto 114 package: helloworld; 115 service Greeter { 116 rpc SayHello(helloworld.HelloRequest) returns (helloworld.HelloReply) {} 117 } 118 119 ``` 120 121### List methods 122 123- List one method with details 124 125 `grpc_cli ls` command also inspects a method given its full name (in the 126 format of \<package\>.\<service\>.\<method\>). 127 128 ```sh 129 $ grpc_cli ls localhost:50051 helloworld.Greeter.SayHello -l 130 ``` 131 132 `helloworld.Greeter.SayHello` is full name of the method. 133 134 output: 135 136 ```proto 137 rpc SayHello(helloworld.HelloRequest) returns (helloworld.HelloReply) {} 138 ``` 139 140### Inspect message types 141 142We can use `grpc_cli type` command to inspect request/response types given the 143full name of the type (in the format of \<package\>.\<type\>). 144 145- Get information about the request type 146 147 ```sh 148 $ grpc_cli type localhost:50051 helloworld.HelloRequest 149 ``` 150 151 `helloworld.HelloRequest` is the full name of the request type. 152 153 output: 154 155 ```proto 156 message HelloRequest { 157 optional string name = 1; 158 } 159 ``` 160 161### Call a remote method 162 163We can send RPCs to a server and get responses using `grpc_cli call` command. 164 165- Call a unary method Send a rpc to a helloworld server at `localhost:50051`: 166 167 ```sh 168 $ grpc_cli call localhost:50051 SayHello "name: 'gRPC CLI'" 169 ``` 170 171 output: `sh message: "Hello gRPC CLI"` 172 173 `SayHello` is (part of) the gRPC method string. Then `"name: 'world'"` is 174 the text format of the request proto message. For information on more flags, 175 look at the comments of `grpc_cli.cc`. 176 177- Use local proto files 178 179 If the server does not have the server reflection service, you will need to 180 provide local proto files containing the service definition. The tool will 181 try to find request/response types from them. 182 183 ```sh 184 $ grpc_cli call localhost:50051 SayHello "name: 'world'" \ 185 --protofiles=examples/protos/helloworld.proto 186 ``` 187 188 If the proto file is not under the current directory, you can use 189 `--proto_path` to specify new search roots (separated by colon on 190 Mac/Linux/Cygwin or semicolon on Windows). 191 192 Note that the tool will always attempt to use the reflection service first, 193 falling back to local proto files if the service is not found. Use 194 `--noremotedb` to avoid attempting to use the reflection service. 195 196- Send non-proto rpc 197 198 For using gRPC with protocols other than protobuf, you will need the exact 199 method name string and a file containing the raw bytes to be sent on the 200 wire. 201 202 ```bash 203 $ grpc_cli call localhost:50051 /helloworld.Greeter/SayHello \ 204 --input_binary_file=input.bin \ 205 --output_binary_file=output.bin 206 ``` 207 208 On success, you will need to read or decode the response from the 209 `output.bin` file. 210