• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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 with cmake:
56
57```
58$ mkdir -p cmake/build
59$ cd cmake/build
60$ cmake -DgRPC_BUILD_TESTS=ON ../..
61$ make grpc_cli
62```
63
64The main file can be found at
65https://github.com/grpc/grpc/blob/master/test/cpp/util/grpc_cli.cc
66
67## Prerequisites
68
69Most `grpc_cli` commands need the server to support server reflection. See
70guides for
71[Java](https://github.com/grpc/grpc-java/blob/master/documentation/server-reflection-tutorial.md#enable-server-reflection)
72, [C++](https://github.com/grpc/grpc/blob/master/doc/server_reflection_tutorial.md)
73and [Go](https://github.com/grpc/grpc-go/blob/master/Documentation/server-reflection-tutorial.md)
74
75Local proto files can be used as an alternative. See instructions [below](#Call-a-remote-method).
76
77## Usage
78
79### List services
80
81`grpc_cli ls` command lists services and methods exposed at a given port
82
83-   List all the services exposed at a given port
84
85    ```sh
86    $ grpc_cli ls localhost:50051
87    ```
88
89    output:
90
91    ```none
92    helloworld.Greeter
93    grpc.reflection.v1alpha.ServerReflection
94    ```
95
96    The `localhost:50051` part indicates the server you are connecting to.
97
98-   List one service with details
99
100    `grpc_cli ls` command inspects a service given its full name (in the format
101    of \<package\>.\<service\>). It can print information with a long listing
102    format when `-l` flag is set. This flag can be used to get more details
103    about a service.
104
105    ```sh
106    $ grpc_cli ls localhost:50051 helloworld.Greeter -l
107    ```
108
109    `helloworld.Greeter` is full name of the service.
110
111    output:
112
113    ```proto
114    filename: helloworld.proto
115    package: helloworld;
116    service Greeter {
117      rpc SayHello(helloworld.HelloRequest) returns (helloworld.HelloReply) {}
118    }
119
120    ```
121
122### List methods
123
124-   List one method with details
125
126    `grpc_cli ls` command also inspects a method given its full name (in the
127    format of \<package\>.\<service\>.\<method\>).
128
129    ```sh
130    $ grpc_cli ls localhost:50051 helloworld.Greeter.SayHello -l
131    ```
132
133    `helloworld.Greeter.SayHello` is full name of the method.
134
135    output:
136
137    ```proto
138    rpc SayHello(helloworld.HelloRequest) returns (helloworld.HelloReply) {}
139    ```
140
141### Inspect message types
142
143We can use `grpc_cli type` command to inspect request/response types given the
144full name of the type (in the format of \<package\>.\<type\>).
145
146-   Get information about the request type
147
148    ```sh
149    $ grpc_cli type localhost:50051 helloworld.HelloRequest
150    ```
151
152    `helloworld.HelloRequest` is the full name of the request type.
153
154    output:
155
156    ```proto
157    message HelloRequest {
158      optional string name = 1;
159    }
160    ```
161
162### Call a remote method
163
164We can send RPCs to a server and get responses using `grpc_cli call` command.
165
166-   Call a unary method Send a rpc to a helloworld server at `localhost:50051`:
167
168    ```sh
169    $ grpc_cli call localhost:50051 SayHello "name: 'gRPC CLI'"
170    ```
171
172    output: `sh message: "Hello gRPC CLI"`
173
174    `SayHello` is (part of) the gRPC method string. Then `"name: 'world'"` is
175    the text format of the request proto message. For information on more flags,
176    look at the comments of `grpc_cli.cc`.
177
178-   Use local proto files
179
180    If the server does not have the server reflection service, you will need to
181    provide local proto files containing the service definition. The tool will
182    try to find request/response types from them.
183
184    ```sh
185    $ grpc_cli call localhost:50051 SayHello "name: 'world'" \
186      --protofiles=examples/protos/helloworld.proto
187    ```
188
189    If the proto file is not under the current directory, you can use
190    `--proto_path` to specify a new search root.
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