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