[DOC] Add CLI section to user documentation.

docs/cli/cheat_sheet.rst

@@ -0,0 +1,68 @@
+.. Parsec Cloud (https://parsec.cloud) Copyright (c) BUSL-1.1 2016-present Scille SAS
+
+.. _doc_cli_cheat_sheet:
+
+===========
+Cheat sheet
+===========
+
+This page aims to provide a quick overview of the most used commands.
+
+
+Device
+======
+
+For more, see :ref:`device <doc_cli_device>`
+
+.. code-block:: shell
+
+    parsec-cli device forget-local -d <DEVICE_ID>
+    parsec-cli device list
+    parsec-cli device change-authentication -d <DEVICE_ID> --<NEW_AUTH_METHOD>
+    parsec-cli device export-recovery-device <DEST> -d <DEVICE_ID>
+    parsec-cli device import-recovery-device --input <RECOVERY_FILE> --label <NEW_DEVICE_LABEL>
+
+
+
+Invite
+======
+
+For more, see :ref:`invite <doc_cli_invite>`
+
+.. code-block:: shell
+
+    parsec-cli invite cancel <INVITATION_TOKEN> -d <DEVICE_ID>
+    parsec-cli invite claim '<INVITATION_LINK>'
+    parsec-cli invite greet <INVITATION_TOKEN> -d <DEVICE_ID>
+    parsec-cli invite list -d <DEVICE_ID>
+    parsec-cli invite user <NEW_USER_EMAIL> -d <DEVICE_ID>
+    parsec-cli invite device -d <DEVICE_ID>
+
+
+User
+====
+
+For more, see :ref:`user <doc_cli_user>`
+
+.. code-block:: shell
+
+    parsec-cli user list -d <DEVICE_ID>
+    parsec-cli user revoke <USER_EMAIL> -d <DEVICE_ID>
+
+
+
+Workspace
+=========
+
+For more, see :ref:`workspace <doc_cli_workspace>`
+
+.. code-block:: shell
+
+    parsec-cli workspace list-users -d <DEVICE_ID> -w <WORKSPACE_ID>
+    parsec-cli workspace archive -d <DEVICE_ID> -w <WORKSPACE_ID> --<STATUS>
+    parsec-cli workspace create -d <DEVICE_ID> <NEW_WORKSPACE_NAME>
+    parsec-cli workspace list -d <DEVICE_ID>
+    parsec-cli workspace import -d <DEVICE_ID> -w <WORKSPACE_ID> <SOURCE> <DEST>
+    parsec-cli workspace share -d <DEVICE_ID> -w <WORKSPACE_ID> -u <USER_ID> -r <ROLE>
+    parsec-cli ls -d <DEVICE_ID> -w <WORKSPACE_ID>
+    parsec-cli rm -d <DEVICE_ID> -w <WORKSPACE_ID> <PATH>

docs/cli/device.rst

@@ -0,0 +1,115 @@
+.. Parsec Cloud (https://parsec.cloud) Copyright (c) BUSL-1.1 2016-present Scille SAS
+
+.. _doc_cli_device:
+
+===================
+Device CLI commands
+===================
+
+In this context, a device is not a physical device but the encrypted file containing the keys allowing the user to access the Organization.
+
+For more see :ref:`Key Parsec concepts <doc_hosting_architecture_concepts>`
+
+List
+====
+
+List all devices available locally. The information provided for each device is:
+
+- short id
+- organization name
+- user name
+- email
+- device label
+- parsec server address
+
+.. code-block:: shell
+
+    parsec-cli device list
+    Found 2 device(s) in /tmp/parsec-testenv-831f316f-5fa7-41f4-a7f8-ba5c5658d79b/config/parsec3/libparsec:
+    052 - WorkOrg: Alice <alice@example.com> @ pc (parsec3://127.0.0.1:7778?no_ssl=true)
+    b1e - PersonalOrg: Alice <alice@example.com> @ laptop (parsec3://127.0.0.1:7778?no_ssl=true)
+
+
+.. _cli_device_forget_local:
+
+Forget-local
+============
+
+This command deletes locally the selected device. This does not involve any server operation.
+
+.. important::
+
+  Please note that if the device file exists elsewhere, it can still be used to
+  access the organization on this server. In other words, this command does not
+  replace user revocation in case of a compromised device.
+
+
+.. code-block:: shell
+
+    parsec-cli device forget-local -d c90
+    You are about to forget the following local device:
+    c90 - Org: Toto <toto@example.com> @ laptop
+    Are you sure? yes
+    The local device has been forgotten
+
+
+Change authentication
+=====================
+
+This command changes the authentication method to password or keyring.
+Other authentication methods are supported by the GUI.
+
+.. code-block:: shell
+
+    parsec-cli device change-authentication -d 052 --password
+    Enter current password for the device:
+    Enter new password for the device:
+    Confirm password:
+    Device authentication changed successfully
+
+
+
+.. note::
+
+    In this example, the authentication method has not changed per se, but
+    the password itself has been updated.
+
+
+Recovery file
+=============
+
+In case you lose access to your device or are unable to authenticate,
+you can setup a recovery device. It consists of two parts that MUST be stored
+separately: the encrypted recovery device file and the passphrase.
+
+These two elements can be used to create a new device.
+
+The inaccessible device cannot be removed from the server, but you can safely
+remove it from your local files (see :ref:`forget local <cli_device_forget_local>`).
+
+Export recovery device
+----------------------
+
+This step must be done before you lose access to you device.
+
+.. code-block:: shell
+
+    parsec-cli device export-recovery-device recovery.txt -d 052
+    Enter password for the device:
+    Recovery device saved at recovery.txt
+    Save the recovery passphrase in a safe place: LIQV-PHTV-K76Y-TSWV-C44U-6ILR-O2JA-XBUC-L27I-J47E-KSID-7OY4-TEEA
+
+
+Import recovery device
+----------------------
+
+This step should be done after you lose access to your device.
+
+.. code-block:: shell
+
+    parsec-cli device import-recovery-device --input recovery.txt --label recovered_device
+    Enter passphrase for the recovery file:
+    Enter password for the new device:
+    Confirm password:
+    New device created:
+    b1e - Org: Alice <alice@example.com> @ recovered_device

docs/cli/first_steps.rst

@@ -0,0 +1,111 @@
+.. Parsec Cloud (https://parsec.cloud) Copyright (c) BUSL-1.1 2016-present Scille SAS
+
+.. _doc_cli_first_steps:
+
+===========
+First steps
+===========
+
+Now that you have installed the Parsec CLI, let's start using it.
+
+.. note::
+
+  The outputs displayed in this documentation are examples and
+  may vary from yours depending on your CLI version.
+
+Help
+====
+
+When in need for information about the Parsec CLI, you can always use `help` as a command
+of its own,
+
+
+.. code-block:: shell
+
+    parsec-cli help
+    Parsec cli
+
+    Usage: parsec-cli <COMMAND>
+
+    Commands:
+      server              Contains subcommands related to server operations
+      device              Contains subcommands related to devices
+      invite              Contains subcommands related to invitation
+      organization        Contains subcommands related to organization
+      user                Contains subcommands related to user
+      workspace           Contains subcommands related to workspace
+      certificate         Contains subcommands related to certificate
+      ls                  List files in a workspace
+      rm                  Remove a file from a workspace
+      tos                 Contains subcommands related to Term of Service (TOS)
+      shared-recovery     Contains subcommands related to shared recovery devices (shamir)
+      mount-realm-export  Mount a realm export as a workspace
+      help                Print this message or the help of the given subcommand(s)
+
+    Options:
+      -h, --help     Print help
+      -V, --version  Print version
+
+or as an option available for any command,
+
+
+.. code-block:: shell
+
+    parsec-cli ls --help
+    List files in a workspace
+
+    Usage: parsec-cli ls [OPTIONS] --workspace <WORKSPACE> [PATH]
+
+    Arguments:
+    [PATH]  Path to list [default: /]
+
+    Options:
+    -w, --workspace <WORKSPACE>    Workspace ID [env: PARSEC_WORKSPACE_ID=]
+        --password-stdin           Read the password from stdin instead of TTY Note: this flag need to be explicitly set, that why it does not have a env var
+    -d, --device <DEVICE>          Device ID [env: PARSEC_DEVICE_ID=]
+    -c, --config-dir <CONFIG_DIR>  Parsec config directory [env: PARSEC_CONFIG_DIR=] [default: /home/aurelia/.config/parsec3/libparsec]
+    -h, --help                     Print help
+
+
+or a group of commands,
+
+
+.. code-block:: shell
+
+    parsec-cli device --help
+    Contains subcommands related to devices
+
+    Usage: parsec-cli device <COMMAND>
+
+    Commands:
+    forget-local            Forget a local device It will still exist on the server but not locally anymore
+    list                    List all devices
+    change-authentication   Change authentication medium for a device
+    export-recovery-device  Export recovery device
+    import-recovery-device  Import recovery device
+    overwrite-server-url    Change the server URL for the device, this is normally not needed
+    help                    Print this message or the help of the given subcommand(s)
+
+    Options:
+    -h, --help  Print help
+
+
+or subcommand
+
+.. code-block:: shell
+
+    parsec-cli device list --help
+    List all devices
+
+    Usage: parsec-cli device list [OPTIONS]
+
+    Options:
+    -c, --config-dir <CONFIG_DIR>  Parsec config directory [env: PARSEC_CONFIG_DIR=] [default: /home/aurelia/.config/parsec3/libparsec]
+    -h, --help                     Print help
+
+
+Commonly used parameters
+------------------------
+
+- ``--device``, ``-d``: the short id of the device used to authenticate the operation. This is needed when a command needs to perform authenticated operations.
+- ``--password-stdin``: to read the password from stdin. This is useful to automate CLI usage.

docs/cli/install_cli.rst

@@ -0,0 +1,57 @@
+.. Parsec Cloud (https://parsec.cloud) Copyright (c) BUSL-1.1 2016-present Scille SAS
+
+.. _doc_cli_install_cli:
+
+==========================
+Install Parsec CLI (Linux)
+==========================
+
+In order to deploy and maintain Parsec Server, you would need to perform some operations with
+Parsec :abbr:`CLI (Command-Line Interface)` for Linux. These operations can be performed from another machine.
+
+Parsec :abbr:`CLI (Command-Line Interface)` is a standalone binary that can be downloaded from
+GitHub releases page.
+
+.. _Parsec CLI: https://github.com/Scille/parsec-cloud/releases/download/v3.9.1-a.0+dev/parsec-cli_3.9.1-a.0+dev_linux-x86_64-musl
+
+1. Download `Parsec CLI`_.
+
+2. Make the file executable
+
+   - Right-click on file, then :menuselection:`Properties --> Allow executing file as program`
+   - Or use the :command:`chmod` command:
+
+     .. code-block:: shell
+
+        chmod +x parsec-cli_3.9.1-a.0+dev_linux-x86_64-musl
+
+3. Verify the installation by running the following command:
+
+   .. code-block:: shell
+
+      ./parsec-cli_3.9.1-a.0+dev_linux-x86_64-musl --version
+
+   The Parsec CLI version should be displayed:
+
+   .. code-block:: shell
+
+      parsec-cli 3.9.1-a.0+dev
+
+4. For convenience, put the executable in ``~/.local/bin``
+
+   .. code-block:: shell
+
+      cp parsec-cli_3.9.1-a.0+dev_linux-x86_64-musl ~/.local/bin
+
+   and make a symbolic link
+
+   .. code-block:: shell
+
+      cd  ~/.local/bin
+      ln -s parsec-cli_3.9.1-a.0+dev_linux-x86_64-musl parsec-cli
+
+   You will be able to execute ``parsec-cli`` from anywhere.
+
+.. tip::
+
+   To update, follow the previous steps with the new version.

docs/cli/introduction.rst

@@ -0,0 +1,12 @@
+.. Parsec Cloud (https://parsec.cloud) Copyright (c) BUSL-1.1 2016-present Scille SAS
+
+.. _doc_cli_introduction:
+
+============
+Introduction
+============
+
+The CLI purpose is twofold:
+
+- a bare-bones alternative to Parsec Desktop or Web application (e.g. to automate periodic file imports)
+- a way to access specific Parsec operations that are not available on the GUI (e.g. monitoring server usage)