Add gnmcli README section

Author: remingtonc

README.md

@@ -8,12 +8,16 @@ This library wraps gNMI functionality to ease usage with Cisco implementations i
 ```bash
 pip install cisco-gnmi
 python -c "import cisco_gnmi; print(cisco_gnmi)"
+gnmcli --help
 ```
 
-This library covers the gNMI defined `capabilities`, `get`, `set`, and `subscribe` RPCs, and helper clients provide OS-specific recommendations. As commonalities and differences are identified this library will be refactored as necessary.
+This library covers the gNMI defined `Capabilities`, `Get`, `Set`, and `Subscribe` RPCs, and helper clients provide OS-specific recommendations. A CLI is also available. As commonalities and differences are identified between OS functionality this library will be refactored as necessary.
 
 It is *highly* recommended that users of the library learn [Google Protocol Buffers](https://developers.google.com/protocol-buffers/) syntax to significantly ease usage. Understanding how to read Protocol Buffers, and reference [`gnmi.proto`](https://github.com/openconfig/gnmi/blob/master/proto/gnmi/gnmi.proto), will be immensely useful for utilizing gNMI and any other gRPC interface.
 
+### gnmcli
+Since `v1.0.5` a gNMI CLI is available when this module is installed. `Capabilities`, `Subscribe`, `Get`, and rudimentary `Set` are supported. The CLI may be useful for simply interacting with a Cisco gNMI service, and also serves as a reference for how to use this `cisco_gnmi` library. CLI usage is documented at the bottom of this README in [gnmcli Usage](#gnmcli-usage).
+
 ### ClientBuilder
 Since `v1.0.0` a builder pattern is available with `ClientBuilder`. `ClientBuilder` provides several `set_*` methods which define the intended `Client` connectivity and a `construct` method to construct and return the desired `Client`. There are several major methods involved here:
 
@@ -181,6 +185,195 @@ If a new `gnmi.proto` definition is released, use `update_protos.sh` to recompil
 ./update_protos.sh
 ```
 
+### gnmicli Usage
+The below details the current `gnmcli` usage options.
+
+```
+gnmcli --help
+usage:
+gnmcli <rpc> [<args>]
+
+Supported RPCs:
+capabilities
+subscribe
+get
+set
+
+See <rpc> --help for RPC options.
+
+
+gNMI CLI demonstrating library usage.
+
+positional arguments:
+  rpc         gNMI RPC to perform against network element.
+
+optional arguments:
+  -h, --help  show this help message and exit
+```
+
+#### Capabilities
+```
+gnmcli capabilities --help
+usage: gnmcli [-h] [-os {None,IOS XR,NX-OS,IOS XE}]
+              [-root_certificates ROOT_CERTIFICATES]
+              [-private_key PRIVATE_KEY]
+              [-certificate_chain CERTIFICATE_CHAIN]
+              [-ssl_target_override SSL_TARGET_OVERRIDE]
+              [-auto_ssl_target_override] [-debug]
+              netloc
+
+Performs Capabilities RPC against network element.
+
+positional arguments:
+  netloc                <host>:<port>
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -os {None,IOS XR,NX-OS,IOS XE}
+                        OS to use.
+  -root_certificates ROOT_CERTIFICATES
+                        Root certificates for secure connection.
+  -private_key PRIVATE_KEY
+                        Private key for secure connection.
+  -certificate_chain CERTIFICATE_CHAIN
+                        Certificate chain for secure connection.
+  -ssl_target_override SSL_TARGET_OVERRIDE
+                        gRPC SSL target override option.
+  -auto_ssl_target_override
+                        Root certificates for secure connection.
+  -debug                Print debug messages
+```
+
+#### Get
+```
+gnmcli get --help
+usage: gnmcli [-h] [-xpath XPATH]
+              [-encoding [{JSON,BYTES,PROTO,ASCII,JSON_IETF}]]
+              [-data_type [{ALL,CONFIG,STATE,OPERATIONAL}]] [-dump_json]
+              [-os {None,IOS XR,NX-OS,IOS XE}]
+              [-root_certificates ROOT_CERTIFICATES]
+              [-private_key PRIVATE_KEY]
+              [-certificate_chain CERTIFICATE_CHAIN]
+              [-ssl_target_override SSL_TARGET_OVERRIDE]
+              [-auto_ssl_target_override] [-debug]
+              netloc
+
+Performs Get RPC against network element.
+
+positional arguments:
+  netloc                <host>:<port>
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -xpath XPATH          XPaths to Get.
+  -encoding [{JSON,BYTES,PROTO,ASCII,JSON_IETF}]
+                        gNMI subscription encoding.
+  -data_type [{ALL,CONFIG,STATE,OPERATIONAL}]
+                        gNMI GetRequest DataType
+  -dump_json            Dump as JSON instead of textual protos.
+  -os {None,IOS XR,NX-OS,IOS XE}
+                        OS to use.
+  -root_certificates ROOT_CERTIFICATES
+                        Root certificates for secure connection.
+  -private_key PRIVATE_KEY
+                        Private key for secure connection.
+  -certificate_chain CERTIFICATE_CHAIN
+                        Certificate chain for secure connection.
+  -ssl_target_override SSL_TARGET_OVERRIDE
+                        gRPC SSL target override option.
+  -auto_ssl_target_override
+                        Root certificates for secure connection.
+  -debug                Print debug messages
+```
+
+#### Subscribe
+Subscribe currently only supports a sampled stream. `ON_CHANGE` is possible but not implemented in the CLI, yet. :)
+```
+gnmcli subscribe --help
+usage: gnmcli [-h] [-xpath XPATH] [-interval INTERVAL] [-dump_file DUMP_FILE]
+              [-dump_json] [-sync_stop]
+              [-encoding [{JSON,BYTES,PROTO,ASCII,JSON_IETF}]]
+              [-os {None,IOS XR,NX-OS,IOS XE}]
+              [-root_certificates ROOT_CERTIFICATES]
+              [-private_key PRIVATE_KEY]
+              [-certificate_chain CERTIFICATE_CHAIN]
+              [-ssl_target_override SSL_TARGET_OVERRIDE]
+              [-auto_ssl_target_override] [-debug]
+              netloc
+
+Performs Subscribe RPC against network element.
+
+positional arguments:
+  netloc                <host>:<port>
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -xpath XPATH          XPath to subscribe to.
+  -interval INTERVAL    Sample interval in seconds for Subscription.
+  -dump_file DUMP_FILE  Filename to dump to. Defaults to stdout.
+  -dump_json            Dump as JSON instead of textual protos.
+  -sync_stop            Stop on sync_response.
+  -encoding [{JSON,BYTES,PROTO,ASCII,JSON_IETF}]
+                        gNMI subscription encoding.
+  -os {None,IOS XR,NX-OS,IOS XE}
+                        OS to use.
+  -root_certificates ROOT_CERTIFICATES
+                        Root certificates for secure connection.
+  -private_key PRIVATE_KEY
+                        Private key for secure connection.
+  -certificate_chain CERTIFICATE_CHAIN
+                        Certificate chain for secure connection.
+  -ssl_target_override SSL_TARGET_OVERRIDE
+                        gRPC SSL target override option.
+  -auto_ssl_target_override
+                        Root certificates for secure connection.
+  -debug                Print debug messages
+```
+
+#### Set
+```
+gnmcli set --help
+usage: gnmcli [-h] [-update_json_config UPDATE_JSON_CONFIG]
+              [-replace_json_config REPLACE_JSON_CONFIG]
+              [-delete_xpath DELETE_XPATH] [-no_ietf] [-dump_json]
+              [-os {None,IOS XR,NX-OS,IOS XE}]
+              [-root_certificates ROOT_CERTIFICATES]
+              [-private_key PRIVATE_KEY]
+              [-certificate_chain CERTIFICATE_CHAIN]
+              [-ssl_target_override SSL_TARGET_OVERRIDE]
+              [-auto_ssl_target_override] [-debug]
+              netloc
+
+Performs Set RPC against network element.
+
+positional arguments:
+  netloc                <host>:<port>
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -update_json_config UPDATE_JSON_CONFIG
+                        JSON-modeled config to apply as an update.
+  -replace_json_config REPLACE_JSON_CONFIG
+                        JSON-modeled config to apply as an update.
+  -delete_xpath DELETE_XPATH
+                        XPaths to delete.
+  -no_ietf              JSON is not IETF conformant.
+  -dump_json            Dump as JSON instead of textual protos.
+  -os {None,IOS XR,NX-OS,IOS XE}
+                        OS to use.
+  -root_certificates ROOT_CERTIFICATES
+                        Root certificates for secure connection.
+  -private_key PRIVATE_KEY
+                        Private key for secure connection.
+  -certificate_chain CERTIFICATE_CHAIN
+                        Certificate chain for secure connection.
+  -ssl_target_override SSL_TARGET_OVERRIDE
+                        gRPC SSL target override option.
+  -auto_ssl_target_override
+                        Root certificates for secure connection.
+  -debug                Print debug messages
+```
+
 ## Licensing
 `cisco-gnmi-python` is licensed as [Apache License, Version 2.0](LICENSE).