Using PGD CLI
=============

What is the PGD CLI?
--------------------

The PGD CLI is a convenient way to connect to and manage your PGD
cluster. To use it, you need a user with PGD superuser privileges or
equivalent. The PGD user with superuser privileges is the :ref:`bdr_superuser role and replication <bdr_superuser role and replication>` 
. An example of an equivalent user is edb_admin on an EDB Cloud Service
distributed high-availability cluster.

..  Important Setting passwords::
   PGD CLI doesn't interactively prompt for your password. You must pass your password using one of the following methods:

- Adding an entry to your 
`.pgpass <https://www.postgresql.org/docs/current/libpq-pgpass.html>`_  , which includes the host, port,
  database name, user name, and password.

- Setting the password in the ``PGPASSWORD`` environment variable.

- Including the password in the connection string.

We recommend the first option, as the other options don’t scale well
with multiple databases, or they compromise password confidentiality.

.. ::
   ## Running the PGD CLI

Once you have :ref:`installed pgd-cli <installing>`  , run the ``pgd`` command to access the PGD
command line interface. The ``pgd`` command needs details about the
host, port, and database to connect to, along with your username and
password.

From PGD 6.5, if the PGD CLI connects to a regular Postgres database
that doesn’t have the BDR extension installed, it displays a clear
warning instead of failing with an ambiguous connection error.

Passing a database connection string
------------------------------------

Use the ``--dsn`` flag to pass a database connection string to the
``pgd`` command. When you pass the connection string with the ``--dsn``
flag, you don’t need a configuration file. The flag takes precedence
even if a configuration file is present. For example:

.. code:: sh

   pgd nodes list --dsn "host=bdr-a1 port=5432 dbname=pgddb user=enterprisedb"

The database conmnection string (DSN) can also be set using the
``PGD_CLI_DSN`` environment variable. For example:

.. code:: sh

   export PGD_CLI_DSN="host=bdr-a1 port=5432 dbname=pgddb user=enterprisedb"
   pgd nodes list

The ``--dsn`` flag takes precedence over the environment variable, so if
both are set, the ``--dsn`` value is used.

See `PGD CLI Command reference <https://www.enterprisedb.com/docs/pgd/latest/reference/cli/command_ref/>`_  for a description of the command options.

Specifying a configuration file
-------------------------------

If a ``pgd-cli-config.yml`` file is in ``/etc/edb/pgd-cli`` or
``$HOME/.edb/pgd-cli`` , ``pgd`` uses it. You can override this behavior
using the optional ``-f`` or ``--config-file`` flag. For example:

.. code:: sh

   pgd nodes list -f /opt/my-config.yml
   __OUTPUT__
   Node Name Group Name   Node Kind Join State Node Status
   - -------- ------------ --------- ---------- -----------
   kaftan    dc1_subgroup data      ACTIVE     Up         
   kaolin    dc1_subgroup data      ACTIVE     Up         
   kaboom    dc1_subgroup data      ACTIVE     Up  

Specifying the output format
----------------------------

Use the ``-o`` or ``--output`` flag to change the default output format
to JSON. For example:

.. code:: sh

   pgd nodes list -o json
   [
     {
       "node_name": "kaftan",
       "node_group_name": "dc1_subgroup",
       "node_kind_name": "data",
       "join_state": "ACTIVE",
       "node_status": "Up",
       "node_id": 3490219809,
       "node_seq_id": 2,
       "node_local_dbname": "pgddb"
     },
     {
       "node_name": "kaolin",
       "node_group_name": "dc1_subgroup",
       "node_kind_name": "data",
       "join_state": "ACTIVE",
       "node_status": "Up",
       "node_id": 2111777360,
       "node_seq_id": 1,
       "node_local_dbname": "pgddb"
     },
     {
       "node_name": "kaboom",
       "node_group_name": "dc1_subgroup",
       "node_kind_name": "data",
       "join_state": "ACTIVE",
       "node_status": "Up",
       "node_id": 2710197610,
       "node_seq_id": 3,
       "node_local_dbname": "pgddb"
     }
   ]

The PGD CLI supports the following output formats.

.. csv-table::
  :header: Setting,Format,Description
  :widths: 12,10,25
  :align: left
  :class: longtable

  `simple`,Tabular,A simple tabular view. (Default).
  `json`,JSON,"Presents the raw data with no formatting. For some commands, the JSON output might show more data than the tabular output, such as extra fields and more detailed messages."
  `psql`,PSQL,A tabular view in the style of PSQL output. format.
  `modern`,Tabular,A tabular view which uses box characters to deliniate the table.
  `markdown`,Markdown,"A Markdown style output which may product long-form, non-tabular output for some commands such as `pgd assess`."

Accessing the command line help
-------------------------------

To list the supported commands, enter:

.. code:: sh

   pgd --help

For help with a specific command and its parameters, enter
``pgd <command_name> --help`` . For example:

.. code:: sh

   pgd nodes list --help

..  Note Avoiding stale data::
   The PGD CLI can return stale data on the state of the cluster if it's still connecting to nodes previously parted from the cluster. Edit the `pgd-cli-config.yml`  file, or change your `--dsn`  settings to ensure you are connecting to active nodes in the cluster.