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