diff --git a/examples/shell/README.md b/examples/shell/README.md
new file mode 100644
index 00000000000000..30ff5783f579fe
--- /dev/null
+++ b/examples/shell/README.md
@@ -0,0 +1,116 @@
+# CHIP Shell Reference
+
+The `chip-shell` firmware exposes configuration and management APIs via a
+command line interface (CLI). Use the shell CLI to experiment with CHIP
+interactively, which can also be used with additional application code. The CHIP
+functional test scripts use the shell CLI to execute test cases.
+
+## Separator and escaping characters
+
+The whitespace character (`' '`) is used to delimit the command name and the
+different arguments, together with tab (`'\t'`) and new line characters (`'\r'`,
+`'\n'`).
+
+Some arguments might require to accept whitespaces on them. For those cases the
+backslash character (`'\'`) can be used to escape separators or the backslash
+itself.
+
+Example:
+
+```bash
+> networkname Test\ Network
+Done
+> networkname
+Test Network
+Done
+>
+```
+
+## CHIP Shell Command List
+
+-   [base64](#base64-decode-b64_string)
+-   [device](README_DEVICE.md)
+-   [echo](#echo-string)
+-   [exit](#exit)
+-   [help](#help)
+-   [rand](#rand)
+-   [version](#version)
+
+## CHIP Shell Command Details
+
+### help
+
+Display a list of all top-level commands supported and a brief description.
+
+```bash
+> help
+  echo            Echo back provided inputs
+  log             Logging utilities
+  rand            Random number utilities
+  base64          Base64 encode / decode utilities
+  device          Device Layer commands
+  exit            Exit the shell application
+  help            List out all top level commands
+  version         Output the software version
+Done
+```
+
+### base64 decode \<b64_string\>
+
+Decode the given base64 string into hex.
+
+```bash
+> base64 decode EjQ=
+1234
+Done
+```
+
+### base64 encode \<hex_string\>
+
+Decode the given hex string into base64.
+
+```bash
+> base64 encode 1234
+EjQ=
+Done
+```
+
+### echo \<string\>
+
+Echo back the provided string to the terminal.
+
+```bash
+> echo hello
+hello
+Done
+```
+
+### exit
+
+Exit the shell terminal. On an embedded system this may trigger a watchdog
+reset.
+
+```bash
+> exit
+Goodbye
+```
+
+### rand
+
+Output a single byte random number.
+
+```bash
+> rand
+103
+Done
+```
+
+### version
+
+Output the version of the CHIP stack.
+
+```bash
+> version
+CHIP 0.0.g54591338-dirty
+Done
+```
diff --git a/examples/shell/README_DEVICE.md b/examples/shell/README_DEVICE.md
new file mode 100644
index 00000000000000..1d9db72f218bad
--- /dev/null
+++ b/examples/shell/README_DEVICE.md
@@ -0,0 +1,83 @@
+# CHIP Shell - Device Layer module
+
+The chip::DeviceLayer APIs may be invoked via the CHIP Shell CLI.
+
+## Command List
+
+-   [help](#help)
+-   [config](#config)
+-   [get](#get-parameter)
+-   [start](#start)
+
+## Command Details
+
+### help
+
+List the Device CLI commands.
+
+```bash
+> device help
+  help            Usage: device <subcommand>
+  start           Start the device layer. Usage: device start
+  get             Get configuration value. Usage: device get <param_name>
+  config          Dump entire configuration of device. Usage: device dump
+Done
+```
+
+### config
+
+Dump the configuration of the device.
+
+```bash
+> device config
+VendorId:        235a
+ProductId:       feff
+ProductRevision: 0001
+SerialNumber:    <None>
+ServiceId:       <None>
+FabricId:        <None>
+PairingCode:     <None>
+DeviceId:        <None>
+DeviceCert:      <None>
+DeviceCaCerts:   <None>
+MfrDeviceId:     <None>
+MfrDeviceCert:   <None>
+MfgDeviceCaCerts:<None>
+```
+
+### get \<parameter\>
+
+-   parameter: name of field to query
+
+Where valid parameter names include:
+
+-   vendorid: Vendor Identifier
+-   productid: Product Identifier
+-   productrev: Product Revision
+-   serial: Serial Number
+-   deviceid: Device Identification Number
+-   cert: Device Certificate
+-   cacerts: Device CA Certificates
+-   mfrdeviceid: Manufacturer Device Identification Number
+-   mfrcert: Manufacturer Device Certificate
+-   mfrcacerts: Manufacturer Device CA Certs
+-   pairingcode: Pairing Code
+-   serviceid: Service Identifier
+-   fabricid: Fabric Identifier
+
+```bash
+> device get vendorid
+235a
+Done
+```
+
+### start
+
+Initialize the chip stack and start the device layer event loop.
+
+```bash
+> device start
+Init CHIP Stack
+Starting Platform Manager Event Loop
+Done
+```