diff options
Diffstat (limited to 'doc/command_line_tool.md')
| -rw-r--r-- | doc/command_line_tool.md | 156 |
1 files changed, 123 insertions, 33 deletions
diff --git a/doc/command_line_tool.md b/doc/command_line_tool.md index 77c3d078ad..082e6402eb 100644 --- a/doc/command_line_tool.md +++ b/doc/command_line_tool.md @@ -58,50 +58,140 @@ $ 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 -### Basic usage +### List services -Send a rpc to a helloworld server at `localhost:50051`: +`grpc_cli ls` command lists services and methods exposed at a given port -``` -$ bins/opt/grpc_cli call localhost:50051 SayHello "name: 'world'" \ - --enable_ssl=false -``` +- List all the services exposed at a given port -On success, the tool will print out + ```sh + $ grpc_cli ls localhost:50051 + ``` -``` -Rpc succeeded with OK status -Response: - message: "Hello world" -``` + output: -The `localhost:50051` part indicates the server you are connecting to. `SayHello` is (part of) the -gRPC method string. Then `"name: 'world'"` is the text format of the request proto message. We are -not using ssl here by `--enable_ssl=false`. For information on more flags, look at the comments of `grpc_cli.cc`. + ```none + helloworld.Greeter + grpc.reflection.v1alpha.ServerReflection + ``` -### Use local proto files + The `localhost:50051` part indicates the server you are connecting to. -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. +- List one service with details -``` -$ bins/opt/grpc_cli call localhost:50051 SayHello "name: 'world'" \ - --protofiles=examples/protos/helloworld.proto --enable_ssl=false -``` + `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. -If the proto files is not under current directory, you can use `--proto_path` to specify a new -search root. + ```sh + $ grpc_cli ls localhost:50051 helloworld.Greeter -l + ``` -### Send non-proto rpc + `helloworld.Greeter` is full name of the service. -For using gRPC with protocols other than probobuf, you will need the exact method name string -and a file containing the raw bytes to be sent on the wire + output: -``` -$ bins/opt/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. + ```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. |