From c398f11263d2cafdde6b243ce709f54808d0a891 Mon Sep 17 00:00:00 2001
From: Thien-Thi Nguyen <ttn@gnuvola.org>
Date: Fri, 4 Feb 2022 02:34:55 -0500
Subject: document ‘libeufin-cli users’ commands
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

specifically:
- users
- users self
- users list
- users create
- users change-password

Also, update the explanations for env vars ‘LIBEUFIN_NEXUS_USERNAME’
and ‘LIBEUFIN_NEXUS_PASSWORD’.
---
 manpages/libeufin-cli.1.rst | 90 +++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 83 insertions(+), 7 deletions(-)

(limited to 'manpages')

diff --git a/manpages/libeufin-cli.1.rst b/manpages/libeufin-cli.1.rst
index 01091c71..29a48285 100644
--- a/manpages/libeufin-cli.1.rst
+++ b/manpages/libeufin-cli.1.rst
@@ -60,10 +60,11 @@ For **libeufin-cli** to be able to communicate with **libeufin-nexus**,
 the following environment variables need to be set:
 
 ``LIBEUFIN_NEXUS_USERNAME``
-  This is the same username chosen by the nexus ``superuser`` command.
+  For some operations (such as ``users create``), this must be the
+  same username chosen by the ``libeufin-nexus superuser`` command.
 
 ``LIBEUFIN_NEXUS_PASSWORD``
-  This is the same username chosen by the nexus ``superuser`` command.
+  This is the password associated with the username.
 
 ``LIBEUFIN_NEXUS_URL``
   This is ``http://localhost:PORT/``, where ``PORT`` is the
@@ -538,27 +539,102 @@ Note that ``--bank-account jrluser`` is the same as in the
 users
 -----
 
-WRITEME
+The ``libeufin-cli users`` command manages users authorized to
+operate Nexus.
+It has several subcommands: self, list, create, change-password.
+The ``create`` and ``change-password`` commands can only be issued
+by the superuser
+(as configured by the ``libeufin-nexus superuser`` command),
+while the ``self`` and ``list`` commands can be issued by any user.
+
+In the following ``users`` examples, we assume that previously
+the command ``libeufin-nexus superuser foo`` was issued, and
+that the current username and password are for that user
+(via environment variables ``LIBEUFIN_NEXUS_USERNAME`` and
+``LIBEUFIN_NEXUS_PASSWORD``, see above).
 
 users self
 ^^^^^^^^^^
 
-WRITEME
+The ``users self`` command displays information for the current user.
+
+For example:
+
+.. code-block:: console
+
+  $ libeufin-cli users self
+  {
+    "username" : "foo",
+    "superuser" : true
+  }
 
 users list
 ^^^^^^^^^^
 
-WRITEME
+The ``users list`` command displays information for all the
+users authorized to operate Nexus.
+
+For example:
+
+.. code-block:: console
+
+  $ libeufin-cli users list
+  {
+    "users" : [ {
+      "username" : "foo",
+      "superuser" : true
+    } ]
+  }
+
+In this example, there is only one user, the superuser ``foo``.
 
 users create
 ^^^^^^^^^^^^
 
-WRITEME
+The ``users create`` command creates a normal (non-superuser) user.
+It takes one argument, the ``USERNAME`` and one option,
+``--password TEXT``.
+If you omit the option, **libeufin-cli** will prompt you for the password.
+
+For example:
+
+.. code-block:: console
+
+  $ libeufin-cli users create --password easy jrluser
+  {
+    "message" : "New user 'jrluser' registered"
+  }
+  $ libeufin-cli users list
+  {
+    "users" : [ {
+      "username" : "foo",
+      "superuser" : true
+    }, {
+      "username" : "jrluser",
+      "superuser" : false
+    } ]
+  }
+
+In this example, we create the same user as for the sandbox examples
+(see above).
+Note that the system now includes two users.
 
 users change-password
 ^^^^^^^^^^^^^^^^^^^^^
 
-WRITEME
+The ``users change-password`` command changes the password for a user.
+It takes one argument, the ``USERNAME`` and one option,
+``--new-password TEXT``.
+If you omit the option, **libeufin-cli** will prompt you for the password.
+
+For example:
+
+.. code-block:: console
+
+  $ libeufin-cli users change-password --new-password hard jrluser
+  {
+    "message" : "Password successfully changed"
+  }
 
 
 permissions
-- 
cgit v1.2.3