From b52db4750ce0e6e19fcdaa6ad121e6feaa278b2e Mon Sep 17 00:00:00 2001
From: Thien-Thi Nguyen <ttn@gnuvola.org>
Date: Mon, 21 Feb 2022 21:49:04 -0500
Subject: document ‘libeufin-cli permissions’ commands
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

specifically:
- permissions
- permissions list
- permissions grant
- permissions revoke
---
 manpages/libeufin-cli.1.rst | 79 ++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 71 insertions(+), 8 deletions(-)

(limited to 'manpages')

diff --git a/manpages/libeufin-cli.1.rst b/manpages/libeufin-cli.1.rst
index 4458a5bc..b6a175f8 100644
--- a/manpages/libeufin-cli.1.rst
+++ b/manpages/libeufin-cli.1.rst
@@ -640,22 +640,85 @@ For example:
 permissions
 -----------
 
-WRITEME
-
-permissions revoke
-^^^^^^^^^^^^^^^^^^
-
-WRITEME
+The ``libeufin-cli permissions`` command manages permissions
+for operations on Nexus.
+It has three subcommands: list, grant, revoke.
+All three commands can only be issued by the superuser.
 
 permissions list
 ^^^^^^^^^^^^^^^^
 
-WRITEME
+The ``permissions list`` command lists the granted permissions.
+At the beginning of a session, there are none:
+
+.. code-block:: console
+
+  $ libeufin-cli permissions list
+  {
+    "permissions" : [ ]
+  }
+
 
 permissions grant
 ^^^^^^^^^^^^^^^^^
 
-WRITEME
+The ``permissions grant`` command adds a permission to the list
+of granted permissions.
+It takes five arguments: ``SUBJECT_TYPE``, ``SUBJECT_ID``,
+``RESOURCE_TYPE``, ``RESOURCE_ID``, ``PERMISSION_NAME``.
+
+FIXME: The subject type and id, resource type and id, are ...
+
+The ``PERMISSION_NAME`` is one of the following:
+
+- ``facade.talerwiregateway.history``
+- ``facade.talerwiregateway.transfer``
+- ``facade.anastasis.history``
+
+For example:
+
+.. code-block:: console
+
+  $ libeufin-cli permissions grant \
+      some-subject-type some-subject-id \
+      some-resource-type some-resource-id \
+      facade.anastasis.history
+  { }
+  $ libeufin-cli permissions list
+  {
+    "permissions" : [ {
+      "subjectType" : "some-subject-type",
+      "subjectId" : "some-subject-id",
+      "resourceType" : "some-resource-type",
+      "resourceId" : "some-resource-id",
+      "permissionName" : "facade.anastasis.history"
+    } ]
+  }
+
+permissions revoke
+^^^^^^^^^^^^^^^^^^
+
+The ``permissions revoke`` command does the opposite of the
+``permissions grant`` command.
+It takes the same arguments as the ``permissions grant`` command:
+``SUBJECT_TYPE``, ``SUBJECT_ID``, ``RESOURCE_TYPE``, ``RESOURCE_ID``,
+``PERMISSION_NAME``.
+
+For example:
+
+.. code-block:: console
+
+  $ libeufin-cli permissions revoke \
+      some-subject-type some-subject-id \
+      some-resource-type some-resource-id \
+      facade.anastasis.history
+  { }
+  $ libeufin-cli permissions list
+  {
+    "permissions" : [ ]
+  }
+
+This example undoes the effect of the previous (``permissions grant``) example.
 
 
 accounts
-- 
cgit v1.2.3