Merge pull request #14203 from y-zeng/grpc_cli_cod

Update grpc_cli doc

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
+
+`grpc_cli ls` command lists services and methods exposed at a given port
 
-Send a rpc to a helloworld server at `localhost:50051`:
+-   List all the services exposed at a given port
 
+    ```sh
+    $ grpc_cli ls localhost:50051
     ```
-$ bins/opt/grpc_cli call localhost:50051 SayHello "name: 'world'" \
-    --enable_ssl=false
+
+    output:
+
+    ```none
+    helloworld.Greeter
+    grpc.reflection.v1alpha.ServerReflection
     ```
 
-On success, the tool will print out
+    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
     ```
-Rpc succeeded with OK status
-Response:
- message: "Hello world"
+
+    `helloworld.Greeter.SayHello` is full name of the method.
+
+    output:
+
+    ```proto
+    rpc SayHello(helloworld.HelloRequest) returns (helloworld.HelloReply) {}
     ```
 
-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`.
+### Inspect message types
 
-### Use local proto files
+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\>).
 
-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.
+-   Get information about the request type
 
+    ```sh
+    $ grpc_cli type localhost:50051 helloworld.HelloRequest
     ```
-$ bins/opt/grpc_cli call localhost:50051 SayHello "name: 'world'" \
-    --protofiles=examples/protos/helloworld.proto --enable_ssl=false
+
+    `helloworld.HelloRequest` is the full name of the request type.
+
+    output:
+
+    ```proto
+    message HelloRequest {
+      optional string name = 1;
+    }
     ```
 
-If the proto files is not under current directory, you can use `--proto_path` to specify a new
-search root.
+### Call a remote method
 
-### Send non-proto rpc
+We can send RPCs to a server and get responses using `grpc_cli call` command.
 
-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
+-   Call a unary method Send a rpc to a helloworld server at `localhost:50051`:
 
+    ```sh
+    $ grpc_cli call localhost:50051 SayHello "name: 'gRPC CLI'"
     ```
-$ bins/opt/grpc_cli call localhost:50051 /helloworld.Greeter/SayHello --input_binary_file=input.bin \
+
+    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 probobuf, 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.
+
+    On success, you will need to read or decode the response from the
+    `output.bin` file.