diff --git a/packages/lobster-tool-codebeamer/README.md b/packages/lobster-tool-codebeamer/README.md
index 2891f34e..b8f22273 100644
--- a/packages/lobster-tool-codebeamer/README.md
+++ b/packages/lobster-tool-codebeamer/README.md
@@ -14,34 +14,68 @@ requirements management tool
 * `lobster-codebeamer`: Extrat requirements from codebeamer.
 
 ## Configuration
-This tool works with an optional config file. In it you can declare which 
-codebeamer fields should be used as 'refs' reference in the codebeamer file.
-
-For the 'refs' reference in config file you can write:
-
-```
+This tool works with an optional config file.
+It allows to configure the following features:
+
+### References
+Codebeamer items can reference other items through
+[Reference Fields](https://support.ptc.com/help/codebeamer/r2.1/en/index.html#page/codebeamer/user_guide/ug_reference_fields.html).
+This piece of information can be extracted by the tool, and serialized into the
+LOBSTER output file.
+It only needs to know which fields to take into account.
+Following the LOBSTER JSON schema, the item references will be added to the
+`refs` property of the LOBSTER item.
+Accordingly, the configuration parameter to specify the codebeamer field names
+is called `refs`, too. 
+It can contain a single field name, or a list of field names.
+Field IDs cannot be used, only the field names.
+
+Examples:
+```json
 {
-"refs" : "cb-fieldname"
+  "refs" : "cb-fieldname"
 }
 ```
 or
-```
+```json
 {
-"refs" : ["cb-fieldname"]
+  "refs" : ["cb-fieldname"]
 }
 ```
 or
-```
+```json
 {
-"refs" : ["cb-fieldname1", "cb-fieldname2"]
+  "refs" : ["cb-fieldname1", "cb-fieldname2"]
 }
 ```
 
-It is also possible to define the codebeamer token in this file:
+### Bearer Authentication Token
+It is also possible to define the Bearer authentication token in the
+configuration file:
+```json
+{
+  "token" : "your-codebeamer-Bearer-token"
+}
 ```
+Note:
+- The Bearer authentication token can also be provided as a command line
+  argument (use `--cb-token=your-codebeamer-Bearer-token`).
+- If the token is provided in the configuration file and as command line
+  argument, then the configuration file takes precedence.
+- If `--cb-user` or `--cb-pass` is given together with a Bearer token (either
+  as a command line argument or through the configuration file), then the
+  Bearer authentication method is used, and the username and/or password are
+  ignored.
+- If neither a token nor a username or password are given, then the tool tries
+  to read the username and password from the `.netrc` file in the user's home
+  directory.
+
+### Example Configuration
+Here is an example configuration file:
+```json
 {
-"refs" : "cb-fieldname",
-"token" : "your cb-token"
+  "refs" : ["derived from", "satisfied by"],
+  "token" : "SomeTokenStringABC123"
 }
 ```