[VOL-1515] Add logging instructions to the CLI README.md
Change-Id: I005b3fd76319cc416406a4ed11f0b1c7c87ea8d1
diff --git a/python/cli/README.md b/python/cli/README.md
deleted file mode 100644
index c810df4..0000000
--- a/python/cli/README.md
+++ /dev/null
@@ -1,14 +0,0 @@
-## CLI (~/cli)
-
-* Add auto-completion for most common args like device and logical device ids
-* Add consistent argument checking
-* Unify code that retrieves data from gRPC
-* Unify code that prints out data/response, to allow:
- * Selectable output mode:
- * JSON
- * Tabular
-* Organize history per sub context so that in each context the commands
- entered in that context will show
-* Metaprogramming [BIG ONE]: Make large part of the commands come from annotations embedded in
- the protobuf files and have corresponding handler auto-generated by protoc
-* Package CLI as docker container, bake it into composition
diff --git a/python/cli/docs/README.md b/python/cli/docs/README.md
new file mode 100644
index 0000000..fbb48d0
--- /dev/null
+++ b/python/cli/docs/README.md
@@ -0,0 +1,116 @@
+# Voltha CLI (~/cli)
+
+## Overview
+
+The Voltha CLI allows a user to manage OLT and ONU devices along with their corresponding logical devices.
+
+
+## Building the CLI
+
+From the voltha-go directory:
+```
+cd python
+source env.sh
+make cli
+```
+
+## Usage
+
+#### Setup (Development Mode)
+Since the CLI does not do much by itself, then to fully use it, you will need a somewhat complete
+set of dependent containers running as well. These will include the rw_core, OLT/ONU adapters and the actual OLT
+ and ONU devices. For the examples below we will use ponsim as the adapters and ponsimv2 as the devices. In order to get
+ everything running we also need Kafka (with zookeeper) and the Etcd KV store.
+
+First run the dependent containers from the voltha-go directory. In the commands below, replace the IP
+with the IP of the host.
+```
+DOCKER_HOST_IP=<Host IP> docker-compose -f compose/docker-compose-zk-kafka-test.yml up -d
+DOCKER_HOST_IP=<Host IP> docker-compose -f compose/docker-compose-etcd.yml up -d
+DOCKER_HOST_IP=<Host IP> docker-compose -f compose/rw_core.yml up -d
+DOCKER_HOST_IP=<Host IP> docker-compose -f compose/cli.yml up -d
+DOCKER_HOST_IP=<Host IP> docker-compose -f compose/adapters-ponsim.yml up -d
+REPOSITORY=voltha/ docker-compose -f compose/ponsim_olt.yml up -d
+REPOSITORY=voltha/ docker-compose -f compose/ponsim_onu.yml up -d
+```
+
+#### Starting the CLI
+
+Now, start the CLI. Password for 'voltha' user is 'admin'. Please see Dockerfile.cli for passwords
+
+```$xslt
+tput rmam // If you are running on MAC for a clean output
+ssh -p 5022 voltha@localhost
+```
+
+At the prompt, if you type ```help``` you will see all the supported commands and sub-commands.
+
+####Provisioning and activating an OLT device
+
+Run the following at the prompt
+
+```$xslt
+preprovision_olt -t ponsim_olt -H <IP of Ponsim OLT>:50060 // Note this is the actial ponsim_olt container IP
+enable <deviceId> // Use the device ID returned in the previous command
+```
+
+The ```enable``` command returns the logical device Id assigned to that OLT. It is typically the MAC address
+(without the ```:```) of the OLT device.
+
+Now go and try out the commands and sub-commands of the CLI.
+
+####Changing the logging level of the RW Core via the CLI
+
+You can dynamically change the logging level on the Voltha RW Core. The change can be done at a package
+level or for the entire RW Core.
+
+The syntax to change log level is as follows:
+
+```
+log -p [package_name] -l log_level
+
+where
+ package_name (optional) is one of:
+ db/kvstore
+ db/model
+ kafka
+ rw_core/core
+ rw_core/flow_decomposition
+ rw_core/graph
+
+ log_level is one of:
+ DEBUG
+ INFO
+ WARNING
+ ERROR
+ CRITICAL
+ FATAL
+```
+
+Below are some examples.
+```$xslt
+log -l ERROR // This sets the entire RW_CORE to output ERROR and above logs for all packages
+log -p rw_core/core -l DEBUG // This sets the rw_core/core package to debug level
+```
+
+Typically, if you want to debug, say something with the kvstore, then you would set the log level for
+the entire RW Core to error followed by setting the log level to debug for the kvstore as shown below.
+```$xslt
+log -l ERROR // This sets the entire RW_CORE to output ERROR and above logs for all packages
+log -p db/kvstore -l DEBUG // This sets the db/kvstore package to debug level
+```
+
+###Future CLI improvements
+
+* Add auto-completion for most common args like device and logical device ids
+* Add consistent argument checking
+* Unify code that retrieves data from gRPC
+* Unify code that prints out data/response, to allow:
+ * Selectable output mode:
+ * JSON
+ * Tabular
+* Organize history per sub context so that in each context the commands
+ entered in that context will show
+* Metaprogramming [BIG ONE]: Make large part of the commands come from annotations embedded in
+ the protobuf files and have corresponding handler auto-generated by protoc
+* Package CLI as docker container, bake it into composition