DOC: more editing of README.md

Author: dmgav

README.md

@@ -1,12 +1,12 @@
 # save-and-restore-api
 
-The repository contains a Python package for communicating with Save-and-Restore service
-(CSS Phoebus). The package provides syncronous (thread-based) and asynchronous (asyncio)
+`save-and-restore-api` is a Python library for communicating with Save-and-Restore service
+(CS Studio Phoebus). The package provides syncronous (thread-based) and asynchronous (asyncio)
 versions of the API functions.
 
-## Examples
+## How to Use the Library
 
-The following code creates a folder node named "My Folder" under the root node:
+The following example code creates a folder node named "My Folder" under the root node:
 
 ```python
 
@@ -23,7 +23,7 @@ with SaveRestoreAPI(base_url="http://localhost:8080/save-restore") as SR:
     print(f"Created folder metadata: {folder}")
 ```
 
-Async version of the same code:
+Here is an async version of the same code:
 
 ```python
 
@@ -39,16 +39,11 @@ async with SaveRestoreAPI(base_url="http://localhost:8080/save-restore") as SR:
     print(f"Created folder metadata: {folder}")
 ```
 
-
 ## `save-and-restore` CLI Tool
 
-The package also provides a simple CLI tool (`save-and-restore`) for performing a small
-set of basic operations on the nodes of the Save-and-Restore service. The tool was
-primarily developed for creating snapshot configurations based on lists of PVs.
-For example, the tool can read a list of PVs from a .sav file generated by IOC autosave
-and create a configuration node based on that list. Currently only autosave files
-are supported, but support for other formats can be added if needed. The list of
-supported functions can also be extended. Current functions are:
+`save-and-restore` CLI tool is installed with the package. The tool allows performing
+a limited set of basic operations on the nodes of the Save-and-Restore service.
+The currently selected set of operations:
 
 - LOGIN: test login credentials;
 
@@ -58,4 +53,43 @@ supported functions can also be extended. Current functions are:
 
 - CONFIG GET: get information about an existing configuration node, including the list of PVs.
 
-Use `save-and-restore -h` to see the list of options.
+The tool was primarily developed for adding snapshot configurations to Save-and-Restore
+based on lists of PVs loaded from local files. Typical use case is to create a configuration
+based on a list of PVs read from an autosave (`.sav`) file saved by an IOC. Currently only
+autosave files are supported, but support for other formats can be added if needed.
+The list of supported functions can also be extended.
+
+## How to use `save-and-restore` CLI Tool
+
+Read the configuration node named 'eiger_config'. Print the full configuration data
+(the list of PVs):
+
+```bash
+save-and-restore --host-url http://localhost:8080/save-restore \
+CONFIG GET --config-name /detectors/imaging/eiger_config --show-data=ON
+```
+
+Create a new configuration node named 'eiger_config'. Load the list of PVs from
+file ``eiger_pvs.sav``. Automatically create any missing parent folders in
+the path:
+
+```bash
+save-and-restore --host-url=http://localhost:8080/save-restore --username=user\
+--create-folders=true CONFIG ADD --config-name=/detectors/imaging/eiger_config \
+--file-name=eiger_pvs.sav --file-format=autosave
+```
+
+Update an existing configuration node named 'eiger_config'. Load the list of PVs
+from the file ``eiger_pvs.sav``:
+
+```bash
+save-and-restore --host-url http://localhost:8080/save-restore --username=user\
+CONFIG UPDATE --config-name /detectors/imaging/eiger_config \
+--file-name eiger_pvs.sav --file-format autosave
+```
+
+Print full list of options:
+
+```bash
+save-and-restore -h
+```