From d96ca8443bfcdc700797718f2af42ab9928b7004 Mon Sep 17 00:00:00 2001
From: Goffi <goffi@goffi.org>
Date: Wed, 1 Nov 2023 14:10:31 +0100
Subject: [PATCH] doc (cli): documentation for the new `call` command:

fix 426
---
 doc/libervia-cli/call.rst | 66 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)
 create mode 100644 doc/libervia-cli/call.rst

diff --git a/doc/libervia-cli/call.rst b/doc/libervia-cli/call.rst
new file mode 100644
index 00000000..50194423
--- /dev/null
+++ b/doc/libervia-cli/call.rst
@@ -0,0 +1,66 @@
+.. _libervia-cli_call:
+
+===============
+call: A/V Calls
+===============
+
+``call`` lets you initiate or receive calls from the terminal.
+
+During a call, a graphical window will be created, displaying your correspondent's video,
+with your own video feed in the bottom right corner.
+
+With the UI present (by default), there are 3 buttons:
+
+- one to (un)mute video with the ``v`` key shortcut
+- one to (un)mute audio with the ``m`` key shortcut
+- one to hang up with the ``h`` key shortcut. ``Ctrl+c`` will have the same effect.
+
+make
+====
+
+Make a call. The primary argument is the JID of the entity you wish to call.
+
+example
+-------
+
+Pierre wants to call Louise::
+
+  $ li call make louise@example.org
+
+receive
+=======
+
+Receive a call. By default, you'll see a confirmation prompt when someone is calling; you
+can then use ``y`` to accept the call or ``n`` to reject it. Use the ``-a JID,
+--auto-accept JID`` option to automatically accept calls from a specific entity (can be
+used multiple times), or the ``--auto-accept-all`` to accept any incoming call.
+
+.. note::
+
+  Accepting a call automatically activates your webcam and microphone, and shares your IP
+  address with the caller. Therefore, using ``--auto-accept-all`` is a security risk. Only
+  use it if you have a very good reason to do so.
+
+
+examples
+--------
+
+Louise is expecting a call. When she receives one, a prompt will ask her to confirm and
+start it::
+
+  $ li call receive
+
+Piotr has a device with a webcam and microphone for observing wildlife. He set the device
+to automatically accept his calls::
+
+  $ li call receive -a piotr@example.net
+
+.. note::
+
+  Libervia CLI will exit once the first accepted call is terminated. Looping in a shell
+  may be necessary to call the same device multiple times.
+
+.. note::
+
+   Since using auto-accept mode activates the webcam and microphone, consider the privacy
+   implications and ensure that no one will be filmed or recorded without their consent.