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