.. _commands:

========
Commands
========

You can supply commands to the :ref:`Croud CLI <getting-started>` tool, like
so:

.. code-block:: console

    sh$ croud [COMMAND] [OPTIONS]

For example:

.. code-block:: console

    sh$ croud login

You can get the list of available commands, like so:

.. code-block:: console

    sh$ croud --help

To get help for a specific command, you can append ``--help``:

.. code-block:: console

    sh$ croud login --help

.. All commands support the ``--env`` flag, which can be used to select between
.. the ``prod`` and ``dev`` environments. This is an internal feature used by
.. developers of the Croud CLI tool itself.

.. rubric:: Table of Contents

.. contents::
   :local:

.. _login:

``login``
=========

CrateDB Cloud uses OAuth2 for authentication.

You must authenticate yourself before interacting with your `CrateDB Cloud`_
account or its resources.

Log in, like so:

.. code-block:: console

    sh$ croud login

This will open a browser window that will present you with an authentication
screen.

.. NOTE::

    Your access token is cached locally, and all subsequent commands will be
    authenticated until you explicitly log out.

.. _logout:

``logout``
==========

To log out, run:

.. code-block:: console

    sh$ croud logout

This will clear your access token. You will then be required to log in again
before interacting with your account or its resources.

.. _me:

``me``
======

Print the username and email address of the currently authenticated user:

.. code-block:: console

    sh$ croud me

.. _config:

``config``
==========

Croud allows you to configure the following variables:

+----------------+------------------------+-----------------------------------+
| Name           | Allowed Values         | Description                       |
+================+========================+===================================+
| ``region``     | One of:                | The region to run a command       |
|                |                        | against. Some resources (e.g.,    |
|                | * ``bregenz.a1``       | clusters) are attached to         |
|                | * ``westeurope.azure`` | specific regions                  |
|                | * ``eastus.azure``     |                                   |
+----------------+------------------------+-----------------------------------+
| ``output-fmt`` | One of:                | The default output format (for    |
|                |                        | commands that produce an output). |
|                |  * ``table``           |                                   |
|                |  * ``json``            |                                   |
+----------------+------------------------+-----------------------------------+

.. _get:

``get``
-------

You can print the value of a configuration variable, like this:

.. code-block:: console

    sh$ croud config get [NAME]

So, for example:

.. code-block:: console

    sh$ croud config get 'region'

Here, the value of the ``region`` configuration variable would be printed.

.. _set:

``set``
-------

You can set configuration variables, like this:

.. code-block:: console

    sh$ croud config set [OPTION] [VALUE]

If you want to set the ``region`` configuration variable, you would use the
``--region`` option.

For example:

.. code-block:: console

    sh$ croud config set --region 'westeurope.azure'

Here, the ``region`` configuration variable is set to ``westeurope.azure``.

.. NOTE::

    If you specify multiple flags, you can set several configuration variables
    at once.

.. _organizations:

``organizations``
=================

The ``organizations`` command allows you to create, modify and view
organization resources.

You must specify a subcommand, like so:

.. code-block:: console

    sh$ croud organizations [SUBCOMMAND] [OPTIONS]

.. _organizations.create:

``create``
----------

The ``create`` subcommand creates an organization:

.. code-block:: console

    sh$ croud organizations create [OPTIONS]

.. NOTE::

    This subcommand is only available to superusers.

Available options:

+-----------------------+----------+--------------------------------+
| Option                | Required | Description                    |
+=======================+==========+================================+
| ``--name <STRING>``   | Yes      | The desired organization name. |
+-----------------------+----------+--------------------------------+
| ``--plan-type <INT>`` | Yes      | The desired plan type.         |
|                       |          |                                |
|                       |          | Options:                       |
|                       |          |                                |
|                       |          | - ``1``                        |
|                       |          | - ``2``                        |
|                       |          | - ``3``                        |
|                       |          | - ``4``                        |
|                       |          | - ``5``                        |
|                       |          | - ``6``                        |
+-----------------------+----------+--------------------------------+

For example:

.. code-block:: console

    sh$ croud organizations create --name 'My Organization' --plan-type '1'

This output format looks like this:

.. code-block:: text

    {
        "id": str,
        "name": str,
        "planType": int
    }

Here, ``id`` is the organization ID assigned by CrateDB Cloud.

.. _organizations.list:

``list``
--------

The ``list`` subcommand prints a list of all the organizations you belong to:

.. code-block:: console

    sh$ croud organizations list [OPTIONS]

Available options:

+---------------------------+----------+----------------------------+
| Option                    | Required | Description                |
+===========================+==========+============================+
| ``--output-fmt <STRING>`` | No       | The desired output format. |
|                           |          |                            |
|                           |          | One of:                    |
|                           |          |                            |
|                           |          | - ``json``                 |
|                           |          | - ``table``                |
+---------------------------+----------+----------------------------+

This output format looks like this:

.. code-block:: text

    [
       {
           "id": str,
           "name": str,
           "planType": int,
           "notification": {
               "alert": {
                   "email": str,
                   "enabled": bool
               }
           }
       }
       ...
   ]

.. organizations.users:

``users``
---------

The ``users`` subcommand allows you to add and remove users from an organization.

You must specify a second subcommand, like so:

.. code-block:: console

    sh$ croud organizations users [SUBCOMMAND] [OPTIONS]

.. NOTE::

    These subcommands are only available to organization admins and superusers.

.. organizations.roles.add:

``add``
~~~~~~~

The ``add`` subcommand adds a new user to an organization.

.. code-block:: console

    sh$ croud organizations users add [OPTIONS]

Available options:

+---------------------------+----------+----------------------------+
| Option                    | Required | Description                |
+===========================+==========+============================+
| ``--user <STRING>``       | Yes      | The email address or ID of |
|                           |          | the user you wish to add to|
|                           |          | the organization.          |
+---------------------------+----------+----------------------------+
| ``--role <STRING>``       | No       | The role FQN of the role   |
|                           |          | you wish to give the user. |
+---------------------------+----------+----------------------------+
| ``--org-id <STRING>``     | No       | The ID of the organization |
|                           |          | you wish to add a user to. |
+---------------------------+----------+----------------------------+

.. organizations.roles.remove:

``remove``
~~~~~~~~~~

The ``remove`` subcommand removes a user from an organization.

.. code-block:: console

    sh$ croud organizations users remove [OPTIONS]

Available options:

+---------------------------+----------+----------------------------+
| Option                    | Required | Description                |
+===========================+==========+============================+
| ``--user <STRING>``       | Yes      | The email address or ID of |
|                           |          | the user you wish to remove|
|                           |          | from the organization.     |
+---------------------------+----------+----------------------------+
| ``--org-id <STRING>``     | No       | The ID of the organization |
|                           |          | you wish to add a user to. |
+---------------------------+----------+----------------------------+

.. _consumers:

``consumers``
=============

The ``consumers`` command allows you to manage consumers.

.. code-block:: console

    sh$ croud consumers [SUBCOMMAND] [OPTIONS]

.. consumers.deploy:

``deploy``
----------

The ``deploy`` subcommand deploys a new consumer.

.. code-block:: console

    sh$ croud consumers deploy [OPTIONS]

Available options:

+-------------------------------------+----------+------------------------------------------+
| Option                              | Required | Description                              |
+=====================================+==========+==========================================+
| ``--consumer-name <STRING>``        | Yes      | The name of the consumer.                |
|                                     |          |                                          |
+-------------------------------------+----------+------------------------------------------+
| ``--cluster-id <STRING>``           | Yes      | The identifier of the CrateDB cluster.   |
|                                     |          |                                          |
+-------------------------------------+----------+------------------------------------------+
| ``--project-id <STRING>``           | Yes      | The identifier of the project in which   |
|                                     |          | the consumer should be deployed.         |
+-------------------------------------+----------+------------------------------------------+
| ``--product-name <STRING>``         | Yes      | The name of the desired consumer         |
|                                     |          | product.                                 |
+-------------------------------------+----------+------------------------------------------+
| ``--tier <STRING>``                 | Yes      | The tier of the desired consumer         |
|                                     |          | product                                  |
|                                     |          |                                          |
|                                     |          | One of:                                  |
|                                     |          |                                          |
|                                     |          | - ``XS``                                 |
|                                     |          | - ``S``                                  |
|                                     |          | - ``M``                                  |
|                                     |          | - ``L``                                  |
|                                     |          | - ``XL``                                 |
+-------------------------------------+----------+------------------------------------------+
| ``--num-instances <INT>``           | No       | The number of consumers to be deployed.  |
|                                     |          | Defaults to ``1``.                       |
+-------------------------------------+----------+------------------------------------------+
| ``--consumer-table <STRING>``       | Yes      | The name of the table in which to        |
|                                     |          | insert.                                  |
+-------------------------------------+----------+------------------------------------------+
| ``--consumer-schema <STRING>``      | Yes      | The name of the schema in which to       |
|                                     |          | insert.                                  |
+-------------------------------------+----------+------------------------------------------+
| ``--eventhub-dsn <STRING>``         | Yes      | The connection string of the Azure       |
|                                     |          | Eventhub.                                |
+-------------------------------------+----------+------------------------------------------+
| ``--eventhub-consumer-group         | Yes      | The consumer group of the Azure          |
| <STRING>``                          |          | Eventhub.                                |
+-------------------------------------+----------+------------------------------------------+
| ``--lease-storage-dsn               | Yes      | The connection string of the lease       |
| <STRING>``                          |          | storage (Azure BLOB storage) of the      |
|                                     |          | consumer.                                |
+-------------------------------------+----------+------------------------------------------+
| ``--lease-storage-container         | Yes      | The container name of the lease storage. |
| <STRING>``                          |          |                                          |
+-------------------------------------+----------+------------------------------------------+

.. TIP:

    Be careful when specifying passwords on the command line. Some
    non-alphanumeric characters may be interpreted in an unexpected way by your
    shell. Use `string delimitation`_ and escape characters as needed.

.. consumers.edit:

``edit``
--------

The ``edit`` subcommand edits existing eventhub
consumers.

.. code-block:: console

    sh$ croud consumers edit [OPTIONS]

Available options:

+-------------------------------------+----------+------------------------------------------+
| Option                              | Required | Description                              |
+=====================================+==========+==========================================+
| ``--consumer-id <STRING>``          | Yes      | The identifier of the consumer.          |
|                                     |          |                                          |
+-------------------------------------+----------+------------------------------------------+
| ``--consumer-table <STRING>``       | No       | The name of the table in which to        |
|                                     |          | insert.                                  |
+-------------------------------------+----------+------------------------------------------+
| ``--consumer-schema <STRING>``      | No       | The name of the schema in which to       |
|                                     |          | insert.                                  |
+-------------------------------------+----------+------------------------------------------+
| ``--eventhub-dsn <STRING>``         | No       | The connection string of the Azure       |
|                                     |          | Eventhub.                                |
+-------------------------------------+----------+------------------------------------------+
| ``--eventhub-consumer-group         | No       | The consumer group of the Azure          |
| <STRING>``                          |          | Eventhub.                                |
+-------------------------------------+----------+------------------------------------------+
| ``--lease-storage-dsn               | No       | The connection string of the lease       |
| <STRING>``                          |          | storage (Azure BLOB storage) of the      |
|                                     |          | consumer.                                |
+-------------------------------------+----------+------------------------------------------+
| ``--lease-storage-container         | No       | The container name of the lease storage. |
| <STRING>``                          |          |                                          |
+-------------------------------------+----------+------------------------------------------+

.. consumers.list:

``list``
--------

By default the command lists all consumers a user can see in their organization.
The list can optionally be filtered by project or cluster.

.. code-block:: console

    sh$ croud consumers list [OPTIONS]

Available options:

+---------------------------+----------+------------------------------------------+
| Option                    | Required | Description                              |
+===========================+==========+==========================================+
| ``--project-id <STRING>`` | No       | The identifier of the project in which   |
|                           |          | the consumer is in.                      |
+---------------------------+----------+------------------------------------------+
| ``--cluster-id <STRING>`` | No       | The identifier of the CrateDB cluster    |
|                           |          | where the consumer inserts data.         |
+---------------------------+----------+------------------------------------------+
| ``--output-fmt <STRING>`` | No       | The desired output format.               |
|                           |          |                                          |
|                           |          | One of:                                  |
|                           |          |                                          |
|                           |          | - ``json``                               |
|                           |          | - ``table``                              |
+---------------------------+----------+------------------------------------------+

.. _projects:

``projects``
============

The ``projects`` command allows you to create, modify and view project
resources.

You must specify a subcommand, like so:

.. code-block:: console

    sh$ croud projects [SUBCOMMAND] [OPTIONS]

.. projects.create:

``create``
----------

The ``create`` subcommand creates a new project in the given organization.
The user has to be admin of the organization to perform this operation.

.. code-block:: console

    sh$ croud projects create [OPTIONS]

Available options:

+---------------------------+----------+----------------------------+
| Option                    | Required | Description                |
+===========================+==========+============================+
| ``--name <STRING>``       | Yes      | The desired project name.  |
+---------------------------+----------+----------------------------+
| ``--org-id <STRING>``     | Yes      | Creates the project in the |
|                           |          | in the chosen organization.|
+---------------------------+----------+----------------------------+
| ``--output-fmt <STRING>`` | No       | The desired output format. |
|                           |          |                            |
|                           |          | One of:                    |
|                           |          |                            |
|                           |          | - ``json``                 |
|                           |          | - ``table``                |
+---------------------------+----------+----------------------------+

.. projects.list:

``list``
--------

The ``list`` subcommand prints a list of all the projects you have access to:

.. code-block:: console

    sh$ croud projects list [OPTIONS]

Available options:

+---------------------------+----------+----------------------------+
| Option                    | Required | Description                |
+===========================+==========+============================+
| ``--region <STRING>``     | Yes      | Filter on region.          |
|                           |          |                            |
|                           |          | One of:                    |
|                           |          |                            |
|                           |          | - ``bregenz.a1``           |
|                           |          | - ``westeurope.azure``     |
|                           |          | - ``eastus.azure``         |
+---------------------------+----------+----------------------------+
| ``--output-fmt <STRING>`` | No       | The desired output format. |
|                           |          |                            |
|                           |          | One of:                    |
|                           |          |                            |
|                           |          | - ``json``                 |
|                           |          | - ``table``                |
+---------------------------+----------+----------------------------+

For example:

.. code-block:: console

    sh$ croud projects list --region 'westeurope.azure'

This output format looks like this:

.. code-block:: text

   [
       {
           "id": str,
           "name": str,
           "region": str,
           "organizationId": str
       }
       ...
   ]

Here, ``id`` is the project ID assigned by CrateDB Cloud.

.. projects.users:

``users``
---------

The ``projects users`` subcommand allows you to add or remove users
from projects.

.. code-block:: console

    sh$ croud projects users [SUBCOMMAND] [OPTIONS]


.. note::

    These commands are privileged to **Organization Admins** only.


.. projects.users.add:

The ``projects users add`` subcommand allows you to add users to projects.

.. code-block:: console

    sh$ croud projects users add [OPTIONS]

Available options:

+---------------------------+----------+----------------------------+
| Option                    | Required | Description                |
+===========================+==========+============================+
| ``--project-id <STRING>`` | Yes      | Select the projects ID to  |
|                           |          | add a user.                |
+---------------------------+----------+----------------------------+
| ``--user <STRING>``       | Yes      | Select a user to add to    |
|                           |          | the project.               |
|                           |          |                            |
|                           |          | Options to select:         |
|                           |          |                            |
|                           |          | - ``email``                |
|                           |          | - ``user-id``              |
+---------------------------+----------+----------------------------+

.. projects.users.remove:

The ``projects users remove`` subcommand allows you to remove users
from projects.

.. code-block:: console

    sh$ croud projects users remove [OPTIONS]

Available options:

+---------------------------+----------+----------------------------+
| Option                    | Required | Description                |
+===========================+==========+============================+
| ``--project-id <STRING>`` | Yes      | Select a project to remove |
|                           |          | a user.                    |
+---------------------------+----------+----------------------------+
| ``--user <STRING>``       | Yes      | Select a user to remove    |
|                           |          | from the project.          |
|                           |          |                            |
|                           |          | Options to select:         |
|                           |          |                            |
|                           |          | - ``email``                |
|                           |          | - ``user-id``              |
+---------------------------+----------+----------------------------+

.. _clusters:

``clusters``
============

The ``clusters`` command allows you to create, modify and view cluster
resources.

You must specify a subcommand, like so:

.. code-block:: console

    sh$ croud clusters [SUBCOMMAND] [OPTIONS]

.. clusters.deploy:

``deploy``
----------

The ``deploy`` subcommand deploys a new CrateDB cluster:

.. code-block: console

    sh$ croud clusters deploy [OPTIONS]

Available options:

+-------------------------------+----------+----------------------------------+
| Option                        | Required | Description                      |
+===============================+==========+==================================+
| ``--product-name <STRING>``   | Yes      | The name of the desired CrateDB  |
|                               |          |  product.                        |
+-------------------------------+----------+----------------------------------+
| ``--tier <STRING>``           | Yes      | The tier of the deployed product.|
|                               |          |                                  |
|                               |          | One of:                          |
|                               |          |                                  |
|                               |          | - ``XS``                         |
|                               |          | - ``S``                          |
|                               |          | - ``M``                          |
|                               |          | - ``L``                          |
|                               |          | - ``XL``                         |
+-------------------------------+----------+----------------------------------+
| ``--project-id <STRING>``     | Yes      | The identifier of the project in |
|                               |          | which the product should be      |
|                               |          | deployed.                        |
+-------------------------------+----------+----------------------------------+
| ``--cluster-name <STRING>``   | Yes      | The CrateDB cluster name.        |
|                               |          |                                  |
+-------------------------------+----------+----------------------------------+
| ``--username <STRING>``       | Yes      | The database username for        |
|                               |          | CrateDB.                         |
+-------------------------------+----------+----------------------------------+
| ``--password <STRING>``       | Yes      | The password for the given       |
|                               |          | database user.                   |
+-------------------------------+----------+----------------------------------+
| ``--version <STRING>``        | Yes      | The version of CrateDB.          |
|                               |          |                                  |
+-------------------------------+----------+----------------------------------+
| ``--unit <STRING>``           | No       | The scale unit of the deployed   |
|                               |          | product.                         |
+-------------------------------+----------+----------------------------------+

.. TIP:

    Be careful when specifying passwords on the command line. Some
    non-alphanumeric characters may be interpreted in an unexpected way by your
    shell. Use `string delimitation`_ and escape characters as needed.

.. clusters.list:

``list``
--------

The ``list`` subcommand prints a list of all the clusters you have access to:

.. code-block:: console

    sh$ croud clusters list [OPTIONS]

Available options:

+---------------------------+----------+----------------------------+
| Option                    | Required | Description                |
+===========================+==========+============================+
| ``--region <STRING>``     | Yes      | Filter on region.          |
|                           |          |                            |
|                           |          | One of:                    |
|                           |          |                            |
|                           |          | - ``bregenz.a1``           |
|                           |          | - ``westeurope.azure``     |
|                           |          | - ``eastus.azure``         |
+---------------------------+----------+----------------------------+
| ``--project-id <STRING>`` | No       | Filter on this project ID. |
+---------------------------+----------+----------------------------+
| ``--output-fmt <STRING>`` | No       | The desired output format. |
|                           |          |                            |
|                           |          | One of:                    |
|                           |          |                            |
|                           |          | - ``json``                 |
|                           |          | - ``table``                |
+---------------------------+----------+----------------------------+

For example:

.. code-block:: console

    sh$ croud clusters list --region 'westeurope.azure'

This would print a list of projects in the ``westeurope.azure`` region.

This output format looks like this:

.. code-block:: text

   [
       {
           "id": str,
           "name": str,
           "numNodes": int,
           "crateVersion": str,
           "projectId": str,
           "username": str,
           "fqdn": str
       }
       ...
   ]

Here, ``id`` is the cluster ID assigned by CrateDB Cloud.

.. _users:

``users``
=========

The ``users`` command allows you to create, modify and view user resources.

You must specify a subcommand, like so:

.. code-block:: console

    sh$ croud users [SUBCOMMAND] [OPTIONS]

.. users.list:

``list``
--------

The ``list`` subcommand allows you to list all users within organizations
that you are part of:

.. code-block:: console

    sh$ croud users list [OPTIONS]

Available options:

+---------------------------+----------+----------------------------+
| Option                    | Required | Description                |
+===========================+==========+============================+
| ``--org-id <STRING>``     | No       | Filter by users in a       |
|                           |          | specific organization. This|
|                           |          | option is only available   |
|                           |          | to super users.            |
+---------------------------+----------+----------------------------+
| ``--no-org <BOOL>``       | No       | Filter by users who are not|
|                           |          | part of any organization.  |
|                           |          | This option is only        |
|                           |          | available to super users.  |
+---------------------------+----------+----------------------------+
| ``--output-fmt <STRING>`` | No       | The desired output format. |
|                           |          |                            |
|                           |          | One of:                    |
|                           |          |                            |
|                           |          | - ``json``                 |
|                           |          | - ``table``                |
+---------------------------+----------+----------------------------+

.. users.roles:

``roles``
---------

The ``roles`` subcommand allows you to create, modify and view user roles.

You must specify a second subcommand, like so:

.. code-block:: console

    sh$ croud users roles [SUBCOMMAND] [OPTIONS]

.. users.roles.add:

``add``
~~~~~~~

The ``add`` subcommand assigns a new role to a user.

.. code-block:: console

    sh$ croud users roles add [OPTIONS]

.. NOTE::

    This subcommand is only available to superusers.

Available options:

+---------------------------+----------+------------------------------+
| Option                    | Required | Description                  |
+===========================+==========+==============================+
| ``--user <STRING>``       | Yes      | The specified user ID.       |
+---------------------------+----------+------------------------------+
| ``--resource <STRING>``   | Yes      | The specified resource ID    |
|                           |          | (organization or project).   |
+---------------------------+----------+------------------------------+
| ``--role <STRING>``       | Yes      | The desired role type. (This |
|                           |          | functions as the `fully      |
|                           |          | qualified role name`_).      |
|                           |          |                              |
|                           |          | See ``users roles list`` for |
|                           |          | more information on viewing  |
|                           |          | a list of available roles.   |
+---------------------------+----------+------------------------------+
| ``--output-fmt <STRING>`` | No       | The desired output format.   |
|                           |          |                              |
|                           |          | One of:                      |
|                           |          |                              |
|                           |          | - ``json``                   |
|                           |          | - ``table``                  |
+---------------------------+----------+------------------------------+

For example:

.. code-block:: console

    sh$ croud users roles add --user '54832319' --resource '14569834' --role 'org_admin'

This output format looks like this:

.. code-block:: text

    {
        "user": {
            "uid": str,
            "email": str,
            "username": str,
            "organizationId": str
        }
    }


.. users.roles.remove:

``remove``
~~~~~~~~~~

The ``remove`` subcommand removes a role from a user.

.. code-block:: console

    sh$ croud users roles remove [OPTIONS]

.. NOTE::

    This subcommand is only available to superusers.

Available options:

+---------------------------+----------+------------------------------+
| Option                    | Required | Description                  |
+===========================+==========+==============================+
| ``--user <STRING>``       | Yes      | The specified user ID.       |
+---------------------------+----------+------------------------------+
| ``--resource <STRING>``   | Yes      | The specified resource ID    |
|                           |          | (organization or project).   |
+---------------------------+----------+------------------------------+
| ``--role <STRING>``       | Yes      | The desired role type. (This |
|                           |          | functions as the `fully      |
|                           |          | qualified role name`_).      |
|                           |          |                              |
|                           |          | See ``users roles list`` for |
|                           |          | more information on viewing  |
|                           |          | a list of available roles.   |
+---------------------------+----------+------------------------------+
| ``--output-fmt <STRING>`` | No       | The desired output format.   |
|                           |          |                              |
|                           |          | One of:                      |
|                           |          |                              |
|                           |          | - ``json``                   |
|                           |          | - ``table``                  |
+---------------------------+----------+------------------------------+

For example:

.. code-block:: console

    sh$ croud users roles remove --user '54832319' --resource '14569834' --role 'org_admin'

This output format looks like this:

.. code-block:: text

    {
        "user": {
            "uid": str,
            "email": str,
            "username": str,
            "organizationId": str
        }
    }

.. users.roles.list:

``list``
~~~~~~~~

The ``list`` subcommand prints a list of all user roles available:

.. code-block:: console

    sh$ croud users roles list [OPTIONS]

Available options:

+---------------------------+----------+----------------------------+
| Option                    | Required | Description                |
+===========================+==========+============================+
| ``--output-fmt <STRING>`` | No       | The desired output format. |
|                           |          |                            |
|                           |          | One of:                    |
|                           |          |                            |
|                           |          | - ``json``                 |
|                           |          | - ``table``                |
+---------------------------+----------+----------------------------+

This output format looks like this:

.. code-block:: text

    [
        {
            "fqn": str,
            "friendlyName": str
        }
        ...
    ]

.. _CrateDB Cloud: https://crate.io/products/cratedb-cloud/
.. _fully qualified role name: https://en.wikipedia.org/wiki/Fully_qualified_name
.. _string delimitation: https://en.wikipedia.org/wiki/Delimiter
