.. _`Using the pywbemcli command line general options`:

Using the pywbemcli command line general options
================================================


.. _`Oveview of the general options`:

Overview of the general options
-------------------------------

General options define:

* The connection to the WBEM server against which the pywbemcli commands are to be
  executed (i.e url, default CIM namespace, security parameters, etc.)
  or the alternative mock of a WBEM server.
  See :ref:`Defining the WBEM server` for details.
* Operation behavior of pywbemcli for requests; i.e. using the pull operations
  vs the :term:`traditional operations`, or the client side timeout.
  See :ref:`Controlling operation behavior and monitoring operations` for
  details.
* Execution options to monitor the requests and responses (statistics keeping,
  and logging of operations) and to display the results.
  See :ref:`Controlling operation behavior and monitoring operations` and
  :ref:`Controlling output formats` for details.
* General options to show the pywbemcli version, and display help for any of
  the command groups or commands.

General options must be entered on the command line before the command group
or command.

For example the following enumerates qualifier declarations and outputs the
result in the ``simple`` table format:

.. code-block:: text

    pywbemcli --output-format simple --server http://localhost qualifier enumerate
    Qualifier Declarations
    Name         Type     Value    Array    Scopes       Flavors
    -----------  -------  -------  -------  -----------  ---------------
    Description  string            False    ANY          EnableOverride
                                                         ToSubclass
                                                         Translatable
    Key          boolean  False    False    PROPERTY     DisableOverride
                                            REFERENCE    ToSubclass

In interactive mode, general options from the command line are defined
once and retain their value throughout the execution of the interactive mode.

General options defined in the command line may be overwritten by specifying
them on interactive mode commands. The resulting new value is used only for
that one command, and is not retained between interactive mode command
executions.

In the following example, the :ref:`--output-format general option` is used
on an interactive mode command to overwrite the default output format, and the
:ref:`--server general option` is used to overwrite the server that was
specified in the command line invocation:

.. code-block:: text

    $ pywbemcli --server http://myserver

    pywbemcli> --output-format table --server http://localhost qualifier enumerate
    Qualifier Declarations
    +-------------+---------+---------+---------+-----------+-----------------+
    | Name        | Type    | Value   | Array   | Scopes    | Flavors         |
    +=============+=========+=========+=========+===========+=================+
    | Description | string  |         | False   | ANY       | EnableOverride  |
    |             |         |         |         |           | ToSubclass      |
    |             |         |         |         |           | Translatable    |
    +-------------+---------+---------+---------+-----------+-----------------+
    | Key         | boolean | False   | False   | PROPERTY  | DisableOverride |
    |             |         |         |         | REFERENCE | ToSubclass      |
    +-------------+---------+---------+---------+-----------+-----------------+


.. _`Defining the WBEM server`:

Defining the WBEM server
^^^^^^^^^^^^^^^^^^^^^^^^

The target WBEM server can be defined on the command line in several ways with
the following arguments :

1. Define connection information for a WBEM server by using the
   :ref:`--server general option` that specifies the URL of the server.

   The following general options can be used for specifying additional
   information for the connection:

   * The :ref:`--default-namespace general option` defines the default namespace
     to be used if a command does not specify a namespace.
   * The :ref:`--user general option` defines the user name for authenticating
     with the WBEM server.
   * The :ref:`--password general option` defines the password for
     authenticating with the WBEM server.
   * The :ref:`--verify general option` defines whether the client verifies
     certificates received from the WBEM server.
   * The :ref:`--certfile general option` defines the client certificate file.
   * The :ref:`--keyfile general option` defines the client key file.
   * The :ref:`--ca-certs general option` defines a collection of certificates
     against which certificates received from the WBEM server are verified.
   * The :ref:`--timeout general option` defines the client side timeout
     for operations.

2. Define a mock WBEM server by using the :ref:`--mock-server general option`.

   The mock WBEM server is part of pywbemcli and allows testing or
   demonstrating pywbemcli without having access to a real WBEM server.
   For details, see :ref:`Mock WBEM server support`.

3. Refer to a persisted connection definition for either a WBEM server or
   mock WBEM server by using the :ref:`--name general option` that
   specifies the name of the connection definition.

   Persisted connection definitions are stored in a :term:`connections file`
   and are managed with the :ref:`Connection command group`.


.. _`Controlling operation behavior and monitoring operations`:

Controlling operation behavior and monitoring operations
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Several general options control the behavior and monitoring of the operations
executed against the WBEM server.

The DMTF specifications allow alternative forms of some operations,
pywbemcli implements this flexibility and controls the choice of either the
pull operations or the traditional operations through the :ref:`--use-pull
general option`. With this option the user can choose to use either type of
operation if that operation is available on the WBEM server. See
:ref:`Pywbemcli and the DMTF pull operations` for more information on pull
operations.

Since the pull operations include the ability to select the maximum size of
returned chunks of data, the :ref:`--pull-max-cnt general option` can be used
to control response chunk sizes.

In many cases it is important to the user to be able to monitor details of the
operations executed against the WBEM server, either the APIs executed in pywbem,
or the HTTP requests and responses and the time statistics for these
operations.

The :ref:`--log general option` provides the capability to log information about
this flow including:

* The API calls and responses/exceptions executed by pywbem.
* the HTTP requests and responses that pass between pywbemcli and the WBEM server.

The :ref:`--log general option` configures the logging including what is logged
and the destination for the log output.

Thus, for example, the following command enumerates qualifiers and writes
the log entries for the CIM-XML HTTP requests and responses to the pywbemcli log
file ``pywbemcli.log``:

.. code-block:: text

   $ pywbemcli --output-format table --server http://localhost --log http=file qualifier enumerate
   <displays table of qualifier declarations>

   $ cat pywbemcli.log
   2019-09-16 21:14:04,296-pywbem.http.1-21020-Connection:1-21020 WBEMConnection(url='http://localhost', ...)
   2019-09-16 21:14:04,297-pywbem.http.1-21020-Request:1-21020 POST /cimom 11 http://localhost
       CIMOperation:'MethodCall' CIMMethod:'EnumerateQualifiers' CIMObject:u'root/cimv2'
       <?xml version="1.0" encoding="utf-8" ?>
       <CIM CIMVERSION="2.0" DTDVERSION="2.0"><MESSAGE ID="1001" PROTOCOLVERSION="1.0">
       ...
       </CIM>
   . . .


.. _`Controlling output formats`:

Controlling output formats
^^^^^^^^^^^^^^^^^^^^^^^^^^

Pywbemcli supports multiple output formats for command results by using the
:ref:`--output-format general option`.

The output formats fall into three groups (table formats, CIM object formats,
and a tree format); however, not all formats are supported or applicable for all
commands. For more details, see :ref:`Output formats`.


.. _`Other miscellaneous general options`:

Other miscellaneous general options
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The :ref:`--verbose general option` displays extra information about the pywbemcli
internal processing, the :ref:`--version general option` displays pywbemcli version
information and the :ref:`--help general option` provides top level help


.. _`General options descriptions`:

General options descriptions
----------------------------

This section defines in detail the requirements, characteristics, and any special
syntax of each general option.


.. _`--server general option`:

--server general option
^^^^^^^^^^^^^^^^^^^^^^^

The argument value of the ``--server``/``-s`` general option is a string that is
the URL of the WBEM server to which pywbemcli will connect, in the format:

.. code-block:: text

    [SCHEME://]HOST[:PORT]

Where:

* **SCHEME**: The protocol to be used. Must be "https" or "http". Default: "https".
* **HOST**: The WBEM server host. Must be a short hostname, fully qualified DNS
  hostname, literal IPv4 address, or literal IPv6 address.
  See :term:`RFC3986` and :term:`RFC6874` for details.
* **PORT**: The WBEM server port to be used.
  Default: 5988 for HTTP, and 5989 for HTTPS.

This option is mutually exclusive with the :ref:`--name general option` and the
:ref:`--mock-server general option` since each defines a connection to a WBEM
server.

In the interactive mode the connection is not actually established until a
command requiring access to the WBEM server is entered.

Examples for the argument value of this option include:

.. code-block:: text

    https://localhost:15345       # https, port 15345, hostname localhost
    http://10.2.3.9               # http, port 5988, IPv4 address 10.2.3.9
    https://10.2.3.9              # https, port 5989, IPv4 address 10.2.3.9
    http://[2001:db8::1234-eth0]  # http, port 5988, IPv6 address 2001:db8::1234, interface eth0


.. _`--name general option`:

--name general option
^^^^^^^^^^^^^^^^^^^^^

The argument value of the ``--name``/``-n`` general option is a string that is
the name of a connection definition in the :term:`connections file`.
The parameters for this named connection definition will be loaded from the
:term:`connections file` to become the current WBEM connection in pywbemcli.

In the interactive mode the connection is not actually established until a
command requiring access to the WBEM server is entered.

This option is mutually exclusive with :ref:`--server general option` and
:ref:`--mock-server general option` since each defines a connection to a WBEM
server.

The following example creates a connection definition named ``myserver``
in the connections file, and then uses that connection to execute
``class get``:

.. code-block:: text

    $ pywbemcli --server http://localhost --user me --password mypw connection save myserver

    $ pywbemcli --name myserver class get CIM_ManagedElement
    <displays MOF for CIM_ManagedElement>

See :ref:`Connection command group` for more information on managing
connections.


.. _`--default-namespace general option`:

--default-namespace general option
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The argument value of the ``--default-namespace``/``-d`` general option is a
string that defines the default :term:`CIM namespace` to use for the target
WBEM server.

If this option is not specified, the default namespace will be ``root/cimv2``.

The default namespace will be used if the ``--namespace``/``-n`` command
option is not used on a command.

Some commands execute against multiple or all namespaces, for example the
the ``class find`` command.


.. _`--user general option`:

--user general option
^^^^^^^^^^^^^^^^^^^^^

The argument value of the ``--user``/``-u`` general option is a string that is
the user name for authenticating with the WBEM server.


.. _`--password general option`:

--password general option
^^^^^^^^^^^^^^^^^^^^^^^^^^

The argument value of the ``--password``/``-p`` general option is a string that is the
password for authenticating with the WBEM server.

This option is normally required if the
:ref:`--user general option` is defined.  If passwords are saved into the
:term:`connections file` they are not encrypted in the file.

If the WBEM operations performed by any pywbemcli command require a password,
the password is prompted for if ``--user``/``-u`` is used (in both modes of
operation) and ``--password``/``-p`` is not used.

.. code-block:: text

    $ pywbemcli --server http://localhost --user me class get
    Enter password: <password>
    . . . <The display output from get class>

If both the ``--user``/``-u`` and ``--password``/``-p`` general options are
used, the command is executed without a password prompt:

.. code-block:: text

    $ pywbemcli --server http://localhost --user me --password blah class get
    . . . <The display output from get class>

If the operations performed by a particular pywbemcli command do not
require a password or no user is supplied, no password is prompted.
For example:

.. code-block:: text

      $ pywbemcli --help
      . . . <help output>

For script integration, it is important to have a way to avoid the interactive
password prompt. This can be done by storing the password string in an
environment variable or specifying it on the command line.
See :ref:`Environment variables for general options`.

The pywbemcli :ref:`Connection export command` outputs the (bash/Windows)
shell commands to set all needed environment variables.

The environment variable output is OS dependent. Thus for example in Unix type
OSs:

.. code-block:: text

    $ pywbemcli --server http://localhost --user fred connection export
    export PYWBEMCLI_SERVER=http://localhost
    export PYWBEMCLI_NAMESPACE=root/cimv2
    ...

This ability can be used to set those environment variables and thus to persist
the connection name in the shell environment, from where it will be used in
any subsequent pywbemcli commands:

.. code-block:: text

    $ eval $(pywbemcli --server http://localhost --user fred connection export)

    $ env | grep PYWBEMCLI
    export PYWBEMCLI_SERVER=http://localhost
    export PYWBEMCLI_NAMESPACE=root/cimv2

    $ pywbemcli server namespaces
    . . . <list of namespaces for the defined server>


.. _`--timeout general option`:

--timeout general option
^^^^^^^^^^^^^^^^^^^^^^^^^^

The argument value of the ``--timeout``/``-t`` general option is an integer that
defines the
client side timeout in seconds. The pywbem client includes a timeout mechanism
that closes a WBEM connection if there is no response to a request to the WBEM
server in the time defined by this value. Pywbemcli defaults to a
predefined timeout (normally 30 seconds) if this option is not defined.


.. _`--verify general option`:

--verify general option
^^^^^^^^^^^^^^^^^^^^^^^

The pair of ``--verify`` and ``--no-verify`` general options control whether or
not the client verifies any certificates received from the WBEM server.

By default or if ``--verify`` is specified, any certificates returned by the
server are verified. If ``--no-verify`` is specified, any certificates returned
by the server are accepted without verification.

This general option uses the approach with two long option names to allow the
user to specifically enable or disable certificate verification when this
general option is used in interactive mode.


.. _`--certfile general option`:

--certfile general option
^^^^^^^^^^^^^^^^^^^^^^^^^

The argument value of the ``--certfile`` general option is the file path of a
PEM file containing a X.509 client certificate to be presented to the WBEM
server during the TLS/SSL handshake, enabling 2-way (mutual) authentication.
This option is used only with HTTPS.

If ``--certfile`` is not used, no client certificate is presented to the server,
resulting in 1-way authentication during the TLS/SSL handshake.

For more information on authentication types, see:
https://pywbem.readthedocs.io/en/stable/client/security.html#authentication-types


.. _`--keyfile general option`:

--keyfile general option
^^^^^^^^^^^^^^^^^^^^^^^^

The argument value of the ``--keyfile`` general option is the file path of a
PEM file containing the private key belonging to the public key that is
part of the X.509 certificate. See :ref:`--certfile general option` for more
information.

Not required if the private key is part of the file defined in the
:ref:`--certfile general option`. ``keyfile`` is not allowed if
:ref:`--certfile general option` is not provided. Default: No client
key file. The client private key should then be part of the file defined by
``--certfile``.


.. _`--ca-certs general option`:

--ca-certs general option
^^^^^^^^^^^^^^^^^^^^^^^^^

The argument value of the ``--ca-certs`` general option is the path name of a file or
directory containing certificates that will be matched against a certificate
received from the WBEM server. The default is OS dependent and is a set of
system directories where certificates are expected to be stored for the client
OS.

Specifying the ``--no-verify`` general option (see :ref:`--verify general option`)
bypasses client verification of the WBEM server certificate.


.. _`--timestats general option`:

--timestats general option
^^^^^^^^^^^^^^^^^^^^^^^^^^

The ``--timestats`` general option is a boolean option that enables the
gathering and display of time
statistics on the interactions with the WBEM server.  If enabled, the
time statistics are output after each command is executed including the
operations executed, the size of the operations, and the execution time.


.. _`--use-pull general option`:

--use-pull general option
^^^^^^^^^^^^^^^^^^^^^^^^^

The argument value of the ``--use-pull``/``-u`` general option determines
whether the pull operations or :term:`traditional operations` are used for the
``instance enumerate``, ``instance references``, ``instance associators``
and ``instance query`` commands. See :ref:`Pywbemcli and
the DMTF pull operations` for more information on pull operations. The choices
for the argument value are as follows:

* ``yes`` - pull operations will be used and if the server does not
  support pull, the request will fail.
* ``no`` - forces pywbemcli to try only the traditional non-pull operations.
* ``either`` - (default) pywbem tries both; first pull operations and then
  :term:`traditional operations`.


.. _`--pull-max-cnt general option`:

--pull-max-cnt general option
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The argument value of the ``--pull-max-cnt`` general option is an integer
passed to the WBEM server with the open and pull operation requests.
This integer tells the server the maximum number of objects
to be returned for each pull request if pull operations are used. This must
be a positive non-zero integer. The default is 1000. See :ref:`Pywbemcli and the
DMTF pull operations` for more information on pull operations.


.. _`--mock-server general option`:

--mock-server general option
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The argument value of the ``--mock-server``/``-m`` general option is a file
path of a MOF file or Python script that loads a mock WBEM server in the
pywbemcli process with mock data (i.e. CIM objects).
This allows pywbemcli to be used without access to a real WBEM server.

This option may be specified multiple times.

This option may be specified multiple times to define multiple MOF and Python
files that make up the definition of a mock server. The files must have the
suffix ".mof" for MOF files and ".py" for Python scripts.

When this option is used, the security options (ex. ``--user``) are irrelevant;
they may be specified but are not used.

The following example creates a mock server with two files defining the mock
data, shows what parameters are defined for the connection, and then saves that
connection named ``mymockserver``:

.. code-block:: text

    $ pywbemcli --mock-server classdefs.mof --mock-server insts.py --default-namespace root/myhome

    pywbemcli> connection show
    name: not-saved (current)
      server:
      mock-server: classdefs.mof, insts.py
      . . .

    pywbemcli> connection save mymockserver

See chapter :ref:`Mock WBEM server support` for more information on defining
the files for a mock server.


.. _`--output-format general option`:

--output-format general option
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The argument value of the ``--output-format``/``-o`` general option is a string
that defines the output format in which the result of any pywbemcli commands
is displayed. The default output format depends on the command.

For details, see :ref:`Output formats`.


.. _`--log general option`:

--log general option
^^^^^^^^^^^^^^^^^^^^

The argument value of the  ``--log``/``-l`` general option defines the destination and
parameters of logging of the requests and responses to the WBEM server.

For details, see :ref:`Pywbemcli defined logging`.


.. _`--verbose general option`:

--verbose general option
^^^^^^^^^^^^^^^^^^^^^^^^

The ``--verbose``/``-v`` general option is a boolean option that enables the
display of extra information about the processing.


.. _`--version general option`:

--version general option
^^^^^^^^^^^^^^^^^^^^^^^^

The ``--version``/``-V`` general option displays the version of this command
and of the pywbem package it uses, and then exits.


.. _`--help general option`:

--help general option
^^^^^^^^^^^^^^^^^^^^^

The ``--help``/``-h`` general option displays help text which describes the
command groups and general options, and then exits.


.. _`Environment variables for general options`:

Environment variables for general options
-----------------------------------------

Pywbemcli defines environment variables corresponding to its general options
as follows:

==============================  ============================
Environment variable            Corresponding general option
==============================  ============================
PYWBEMCLI_SERVER                ``--server``
PYWBEMCLI_NAME                  ``--name``
PYWBEMCLI_USER                  ``--user``
PYWBEMCLI_PASSWORD              ``--password``
PYWBEMCLI_OUTPUT_FORMAT         ``--output-format``
PYWBEMCLI_DEFAULT_NAMESPACE     ``--default-namespace``
PYWBEMCLI_TIMEOUT               ``--timeout``
PYWBEMCLI_KEYFILE               ``--keyfile``
PYWBEMCLI_CERTFILE              ``--certfile``
PYWBEMCLI_CACERTS               ``--ca-certs``
PYWBEMCLI_USE_PULL              ``--use-pull``
PYWBEMCLI_PULL_MAX_CNT          ``--pull-max-cnt``
PYWBEMCLI_STATS_ENABLED         ``--timestats``
PYWBEMCLI_MOCK_SERVER (1)       ``--mock-server``
PYWBEMCLI_LOG                   ``--log``
==============================  ============================

Notes:

(1) The ``--mock-server`` general option can be specified multiple times. To
    do that with the PYWBEMCLI_MOCK_SERVER environment variable, separate
    the multiple path names with space.

If these environment variables are set, the corresponding general options
default to the value of the environment variables.
If both an environment variable and its corresponding general option are
set, the command line option overrides the environment variable with no
warning.
Environment variables are not provided for command options or command arguments.

In the following example, the pywbemcli command uses server
``http://localhost`` defined by the environment variable:

.. code-block:: text

      $ export PYWBEMCLI_SERVER=http://localhost
      $ pywbemcli class get CIM_ManagedElement
        <displays MOF for CIM_ManagedElement>

The pywbemcli :ref:`Connection export command` outputs the (bash/Windows)
shell commands to set all needed environment variables:

.. code-block:: text

    $ pywbemcli --server http://localhost --user fred connection export
    export PYWBEMCLI_SERVER=http://localhost
    export PYWBEMCLI_NAMESPACE=root/cimv2
    . . .

This ability can be used to set those environment variables and thus to persist
the connection name in the shell environment, from where it will be used in
any subsequent pywbemcli commands:

.. code-block:: text

    $ eval $(pywbemcli --server http://localhost --user fred)

    $ env | grep PYWBEMCLI
    export PYWBEMCLI_SERVER=http://localhost
    export PYWBEMCLI_NAMESPACE=root/cimv2
    . . .

    $ pywbemcli server namespaces
    . . . <list of namespaces for the defined server>


.. _`Pywbemcli and the DMTF pull operations`:

Pywbemcli and the DMTF pull operations
--------------------------------------

The DMTF specifications and pywbem includes two ways to execute the enumerate
instance type operations (``Associators``, ``References``,``
EnumerateInstances``, ``ExecQuery``):

* The :term:`traditional operations` (ex. ``EnumerateInstances``)
* The pull operations (ex. ``OpenEnumerateInstances``, etc.)

Pywbem implements an overlay of the above two operations called the ``Iter..``
operations where each ``Iter..`` operation executes either the traditional or
pull operation depending on a parameter of the connection.

While the pull operations may not be supported by all WBEM servers they can be
significantly more efficient for large responses when they are available.
Pywbem implements the client side of these operation and pywbemcli provides for
the use of these operations through two general options:

* ``--use-pull`` - This option allows the user to select from the
  the following alternatives:

  * ``either`` - (default) pywbemcli first tries the open operation and if that is not
    implemented by the server retries the operation with the corresponding
    traditional operation. The result of this first operation determines whether
    pull or the traditional operation are used for any further requests
    during the current pywbem interactive session.


  * ``yes`` - Forces the use of the pull operations and fails if that is not
    implemented by the server.

  * ``no`` - Forces the use of the traditional operation.

* ``--pull-max-cnt`` - Sets the maximum count of objects the server is allowed
  to return for each open/pull operation. The default is 1000 objects which
  from experience is a logical choice.

The default alternative ``either`` is probably the most logical setting for
``--use-pull``, unless you are specifically testing the use of pull
operations.

However, there are some limitations with using the ``either`` choice as follows:

* The original operations did not support the filtering of responses with a
  query language query (``--filter-query-language`` and ``--filter-query`` )
  which requests that the WBEM server filter
  the responses before they are returned. This can greatly reduce the size of
  the responses if effectively used but is used only when the pull operations
  are available on the server.

* The pull operations do not support some of the options that traditional
  operations do:

* ``--include-qualifiers`` - Since even the traditional operations specification
  deprecated this option and the user cannot depend on it being honored,
  the most logical solution is to never use this option.

* ``--local-only`` - Since even the traditional operations specification
  deprecated this option and the user cannot depend on it being honored by
  the WBEM server, the most logical solution is to never use this option.

The following example forces the use of the pull operations and expects the
WBEM server to return no more than 10 instances per request. It fails if the
pull operations are not supported in the WBEM server:

.. code-block:: text

    $ pywbemcli --server http://localhost --use-pull=yes --pull-max-cnt=10 instance enumerate CIM_Foo


.. _`Output formats`:

Output formats
--------------

Pywbemcli supports various output formats for the command result. The output
format can be selected with the ``--output-format``/``-o`` option.

The output formats fall into three groups:

* **Table formats** - The :ref:`Table formats` format the result as a table
  with rows and columns. Many of the result types allow table formatted
  response display including:

  * ``instance get``, ``instance enumerate``, ``instance references``,
    ``instance associators`` where the table formats are alternatives to the
    CIM model formats that shows the properties for each instance as a column
    in a table.
  * ``instance count``
  * ``server`` commands
  * ``class find``
  * ``connection`` commands

* **CIM object formats** - The :ref:`CIM object formats` format a result that
  consists of CIM objects in MOF, CIM-XML or pywbem repr format. All of the
  commands that return CIM objects support these output formats.

* **ASCII tree format** - The :ref:`ASCII tree format` formats the result
  as a tree, using ASCII characters to represent the tree. The only command
  supporting the ASCII tree format is ``class tree``, and it supports only
  that one output format.

When an unsupported output format is specified for a command response, it is
ignored and a default output format is used instead.  For example, the command
``class enumerate`` only supports the CIM object formats and always outputs
in those formats.


.. _`Table formats`:

Table formats
^^^^^^^^^^^^^

The different variations of the table format define different formatting of the
borders for tables. The following are examples of the table formats with a
single command ``class find CIM_Foo``:

* ``--output-format table``: Tables with a single-line border. This is the default:

  .. code-block:: text

    Find class CIM_Foo*
    +-------------+-----------------+
    | Namespace   | Classname       |
    |-------------+-----------------|
    | root/cimv2  | CIM_Foo         |
    | root/cimv2  | CIM_Foo_sub     |
    | root/cimv2  | CIM_Foo_sub2    |
    | root/cimv2  | CIM_Foo_sub_sub |
    +-------------+-----------------+

* ``--output-format simple``: Tables with a line between header row and data
  rows, but otherwise without borders:

  .. code-block:: text

    Find class CIM_Foo*
    Namespace    Classname
    -----------  ---------------
    root/cimv2   CIM_Foo
    root/cimv2   CIM_Foo_sub
    root/cimv2   CIM_Foo_sub2
    root/cimv2   CIM_Foo_sub_sub

* ``--output-format plain``: Tables do not use any pseudo-graphics to draw borders:

  .. code-block:: text

    Find class CIM_Foo*
    Namespace    Classname
    root/cimv2   CIM_Foo
    root/cimv2   CIM_Foo_sub
    root/cimv2   CIM_Foo_sub2
    root/cimv2   CIM_Foo_sub_sub

* ``--output-format grid``: Tables tables formatted by Emacs' `table.el`
  package. It corresponds to ``grid_tables`` in Pandoc Markdown extensions:

  .. code-block:: text

    Find class CIM_Foo*
    +-------------+-----------------+
    | Namespace   | Classname       |
    +=============+=================+
    | root/cimv2  | CIM_Foo         |
    +-------------+-----------------+
    | root/cimv2  | CIM_Foo_sub     |
    +-------------+-----------------+
    | root/cimv2  | CIM_Foo_sub2    |
    +-------------+-----------------+
    | root/cimv2  | CIM_Foo_sub_sub |
    +-------------+-----------------+


* ``--output-format rst``: Tables in `reStructuredText`_ markup:

  .. code-block:: text

    Find class CIM_Foo*
    ===========  ===============
    Namespace    Classname
    ===========  ===============
    root/cimv2   CIM_Foo
    root/cimv2   CIM_Foo_sub
    root/cimv2   CIM_Foo_sub2
    root/cimv2   CIM_Foo_sub_sub
    ===========  ===============

* ``--output-format psql``: Like tables formatted by Postgres' psql cli:

  .. code-block:: text

    Find class CIM_Foo*
    ===========  ===============
    Namespace    Classname
    ===========  ===============
    root/cimv2   CIM_Foo
    root/cimv2   CIM_Foo_sub
    root/cimv2   CIM_Foo_sub2
    root/cimv2   CIM_Foo_sub_sub
    ===========  ===============

* ``--output-format html``: Tables formatted as html table:

  .. code-block:: text

    <p>Find class CIM_Foo*</p>
    <table>
    <thead>
    <tr><th>Namespace  </th><th>Classname      </th></tr>
    </thead>
    <tbody>
    <tr><td>root/cimv2 </td><td>CIM_Foo        </td></tr>
    <tr><td>root/cimv2 </td><td>CIM_Foo_sub    </td></tr>
    <tr><td>root/cimv2 </td><td>CIM_Foo_sub2   </td></tr>
    <tr><td>root/cimv2 </td><td>CIM_Foo_sub_sub</td></tr>
    </tbody>
    </table>

.. _`reStructuredText`: http://docutils.sourceforge.net/docs/user/rst/quickref.html#tables
.. _`Mediawiki`: http://www.mediawiki.org/wiki/Help:Tables
.. _`HTML`: https://www.w3.org/TR/html401/struct/tables.html
.. _`LaTeX`: https://en.wikibooks.org/wiki/LaTeX/Tables
.. _`JSON`: http://json.org/example.html


.. _`CIM object formats`:

CIM object formats
^^^^^^^^^^^^^^^^^^

The output of CIM objects allows multiple formats as follows:

* ``--output-format mof``: Format for CIM classes, CIM instances, and CIM Parameters.

  :term:`MOF` is the format used to define and document the CIM models released
  by the DMTF and SNIA. It textually defines the components and structure and
  data of CIM elements such as classes, instances, and qualifier declarations:

  .. code-block:: text

      instance of CIM_Foo {
         InstanceID = "CIM_Foo1";
         IntegerProp = 1;
      };

* ``--output-format xml``: :term:`CIM-XML` format for CIM elements such as classes,
  instances and qualifier declarations. Besides being used as a protocol for WBEM
  servers, CIM-XML is also an alternative format for representing the CIM models
  released by the DMTF and SNIA. The XML syntax is defined in the DMTF
  specification :term:`DSP0201`.

  This is the format used in the DMTF CIM-XML protocol:

  .. code-block:: text

      <VALUE.OBJECTWITHLOCALPATH>
          <LOCALINSTANCEPATH>
              <LOCALNAMESPACEPATH>
                  <NAMESPACE NAME="root"/>
                  <NAMESPACE NAME="cimv2"/>
              </LOCALNAMESPACEPATH>
              <INSTANCENAME CLASSNAME="CIM_Foo">
                  <KEYBINDING NAME="InstanceID">
                      <KEYVALUE VALUETYPE="string">CIM_Foo1</KEYVALUE>
                  </KEYBINDING>
              </INSTANCENAME>
          </LOCALINSTANCEPATH>
          <INSTANCE CLASSNAME="CIM_Foo">
              <PROPERTY NAME="InstanceID" PROPAGATED="false" TYPE="string">
                  <VALUE>CIM_Foo1</VALUE>
              </PROPERTY>
              <PROPERTY NAME="IntegerProp" PROPAGATED="false" TYPE="uint32">
                  <VALUE>1</VALUE>
              </PROPERTY>
          </INSTANCE>
      </VALUE.OBJECTWITHLOCALPATH>

* ``--output-format repr``: Python repr format of the objects.

  This is the structure and data of the pywbem Python objects representing these
  CIM objects and can be useful in understanding the pywbem interpretation of the
  CIM objects:

  .. code-block:: text

      CIMInstance(classname='CIM_Foo', path=CIMInstanceName(classname='CIM_Foo',
          keybindings=NocaseDict({'InstanceID': 'CIM_Foo1'}), namespace='root/cimv2',
          host=None),
          properties=NocaseDict({
            'InstanceID': CIMProperty(name='InstanceID',
              value='CIM_Foo1', type='string', reference_class=None, embedded_object=None,
              is_array=False, array_size=None, class_origin=None, propagated=False,
              qualifiers=NocaseDict({})),
            'IntegerProp': CIMProperty(name='IntegerProp', value=1, type='uint32',
                reference_class=None, embedded_object=None, is_array=False,
                array_size=None, class_origin=None, propagated=False,
                qualifiers=NocaseDict({}))}), property_list=None,
                qualifiers=NocaseDict({}))

  NOTE: The above is output as a single line and has been manually formatted for
  this documentation.

* ``--output-format txt``: Python str format of the objects.

  This should be considered the output of last resort as it simply uses
  the ``__str__()`` method of the Python class for each CIM object to output.

  Thus, for example the a ``class enumerate`` of a model with only a single
  class is of the form:

  .. code-block:: text

      CIMClass(classname='CIM_Foo', ...)


.. _`ASCII tree format`:

ASCII tree format
^^^^^^^^^^^^^^^^^

This output format is an ASCII based output that shows the tree structure of
the results of the ``class tree`` command. It is the only output format
supported by this command, and therefore it is automatically selected and
cannot be specified explicitly with the ``--output-format`` option.

.. code-block:: text

    $ pywbemcli --mock-server tests/unit/simple_mock_model.mof class tree
    root
    +-- CIM_Foo
        +-- CIM_Foo_sub
        |   +-- CIM_Foo_sub_sub
        +-- CIM_Foo_sub2

This shows a very simple mock repository with 4 classes where CIM_Foo is the
top level in the hierarchy, CIM_Foo_sub and CIM_Foo_sub2 are its subclasses, and
CIM_Foo_sub_sub is the subclass of CIM_Foo_sub.


.. _`Pywbemcli defined logging`:

Pywbemcli defined logging
-------------------------

Pywbemcli provides logging to either a file or the standard error stream
of information passing between the pywbemcli client and a WBEM server using the
standard Python logging facility.

Logging is configured and enabled using the ``--log`` general option on the
commmand line or the `PYWBEMCLI_LOG` environment variable.

Pywbemcli can log operation calls that send
requests to a WBEM server and their responses and the HTTP messages between
the pywbemcli client and the WBEM server including both the pywbem APIs
and their responses and the HTTP requests and responses.

The default is no logging if the ``--log`` option is not specified.

The argument value of the ``--log`` option and the value of the `PYWBEMCLI_LOG`
environment variable is a log configuration string with the format defined in
the ABNF rule ``LOG_CONFIG_STRING``, below. The log configuration string
defines a list of
one or more log configurations, each with fields ``COMPONENT``, ``DESTINATION``,
and ``DETAIL``:

.. code-block:: text

    LOG_CONFIG_STRING := CONFIG [ "," CONFIG ]
    CONFIG            := COMPONENT [ "=" DESTINATION [ ":" DETAIL ]]
    COMPONENT         := ( "all" / "api" / "http" )
    DESTINATION       := ( "stderr" / "file" )
    DETAIL            := ( "all" / "path" / "summary" )

For example the following log configuration string logs the pywbem API calls
and writes summary information to a log file and the HTTP requests and
responses to stderr:

.. code-block:: text

    $ pywbemcli --log api=file:summary,http=stderr

The simplest log configuration string to enable logging is ``all=stderr`` or
``all=file``.

The ``COMPONENT`` field defines the component for which logging is enabled:

* ``api`` - Logs the calls to the pywbem methods that make requests to a
  WBEM server. This logs both the requests and response including any
  exceptions generated by error responses from the WBEM server.
* ``http`` - Logs the headers and data for HTTP requests and responses to the
  WBEM server.
* ``all`` - (Default) Logs both the ``api`` and ``http`` components.

The ``DESTINATION`` field specifies the log destination:

* ``stderr`` - Output log to stderr.
* ``file`` - (default) Log to the pywbemcli log file ``pywbemcli.log`` in
  the current directory.  Logs are appended to an existing log file.

The ``DETAIL`` component of the log configuration string defines the level of
logging information for the api and http components.  Because enormous quantities
of information can be generated this option exists to limit the amount of
information generated. The possible keywords are:

* ``all`` - (Default) Logs the full request including all input parameters and
  the complete response including all data. Exceptions are fully logged.

* ``paths`` - Logs the full request but only the path component of the
  `api` responses. This reduces the data included in the responses.
  Exceptions are fully logged.

* ``summary`` - Logs the requests but only the count of objects received
  in the response.  Exceptions are fully logged.

The log output is routed to the output defined by ``DESTINATION`` and includes the
information determined by the ``COMPONENT`` and ``DETAIL`` fields.

The log output format is:

.. code-block:: text

    <Date time>-<Component>.<connection id>-<Direction>:<connection id> <PywbemOperation>(<data>)

For example, logging only of the summary  API information would look something
like the following:

.. code-block:: text

    $ pywbemcli -s http://localhost -u blah -p pw -l api=file:summary class enumerate -o

produces log output for the class enumerate operation in the log file
pywbemcli.log as follows showing the input parameters to the pywbem method
``EnumerateClassName`` and the number of objects in the response:

.. code-block:: text

    2019-07-09 18:27:22,103-pywbem.api.1-27716-Request:1-27716 EnumerateClassNames(ClassName=None, DeepInheritance=False, namespace=None)
    2019-07-09 18:27:22,142-pywbem.api.1-27716-Return:1-27716 EnumerateClassNames(list of str; count=103)


.. _`Pywbemcli persisted connection definitions`:

Pywbemcli persisted connection definitions
------------------------------------------

Pywbemcli can manage persisted connection definitions via the
:ref:`Connection command group`. These connection definitions are persisted in
a :term:`connections file` named ``pywbemcli_connection_definitions.yaml`` in
the current directory. A connection definition has a name
and defines all parameters necessary to connect to a WBEM server. Once defined
these connection definitions can be used with the :ref:`--name general option`
or in the interactive mode by defining a current connection with the
:ref:`connection select command`.

A new persistent connection definition can be created with the
:ref:`connection save command`.

At any point in time, pywbemcli can communicate with only a single WBEM server.
That is the *current connection*.
In the command mode, this is the WBEM server defined by the general options
``--server`` or ``--mock-server`` or ``--name``.  In the interactive mode, the
current connection can be changed within an interactive session using the
:ref:`connection select command` so that within a single session, the user can
work with multiple WBEM servers (at different points in time).

The following example creates a persisted connection definition, using
interactive mode:

.. code-block:: text

    $ pywbemcli

    pywbemcli> --server http://localhost --user usr1 --password blah connection save testconn

    pywbemcli> connection list
    WBEM server connections: (#: default, *: current)
    +-----------+------------------+-------------+--------+-----------+----------+----------------------------------------+
    | name      | server           | namespace   | user   |   timeout | verify   | mock-server                            |
    |-----------+------------------+-------------+--------+-----------+----------+----------------------------------------|
    | testconn  | http://localhost | root/cimv2  | usr1   |        30 | True     |                                        |
    +-----------+------------------+-------------+--------+-----------+----------+----------------------------------------+

Since the connection definition is persisted, it is available in command mode
as well as in new interactive sessions:

.. code-block:: text

    $ pywbemcli connection list
    WBEM server connections: (#: default, *: current)
    +-----------+------------------+-------------+--------+-----------+----------+----------------------------------------+
    | name      | server           | namespace   | user   |   timeout | verify   | mock-server                            |
    |-----------+------------------+-------------+--------+-----------+----------+----------------------------------------|
    | testconn  | http://localhost | root/cimv2  | usr1   |        30 | True     |                                        |
    +-----------+------------------+-------------+--------+-----------+----------+----------------------------------------+

    $ pywbemcli

    pywbemcli> connection list
    WBEM server connections: (#: default, *: current)
    +-----------+------------------+-------------+--------+-----------+----------+----------------------------------------+
    | name      | server           | namespace   | user   |   timeout | verify   | mock-server                            |
    |-----------+------------------+-------------+--------+-----------+----------+----------------------------------------|
    | testconn  | http://localhost | root/cimv2  | usr1   |        30 | True     |                                        |
    +-----------+------------------+-------------+--------+-----------+----------+----------------------------------------+

Other connection definitions can be added, this time using command mode:

.. code-block:: text

    $ pywbemcli --server http://blah2 --user you --password xxx connection save Ronald

    $ pywbemcli connection list
    WBEM server connections: (#: default, *: current)
    +-----------+------------------+-------------+--------+-----------+----------+----------------------------------------+
    | name      | server           | namespace   | user   |   timeout | verify   | mock-server                            |
    |-----------+------------------+-------------+--------+-----------+----------+----------------------------------------|
    | Ronald    | http://blah2     | root/cimv2  | you    |        30 | True     |                                        |
    | testconn  | http://localhost | root/cimv2  | usr1   |        30 | True     |                                        |
    +-----------+------------------+-------------+--------+-----------+----------+----------------------------------------+

The following example shows how to select current connections in interactive
mode. Note the marker ``*`` in front of the name, which indicates the current
connection. The :ref:`connection show command` when used without a connection
name shows the current connection:

.. code-block:: text

    $ pywbemcli

    pywbemcli> connection select Ronald

    pywbemcli> connection list
    WBEM server connections: (#: default, *: current)
    +-----------+------------------+-------------+--------+-----------+----------+----------------------------------------+
    | name      | server           | namespace   | user   |   timeout | verify   | mock-server                            |
    |-----------+------------------+-------------+--------+-----------+----------+----------------------------------------|
    | *Ronald   | http://blah2     | root/cimv2  | you    |        30 | True     |                                        |
    | testconn  | http://localhost | root/cimv2  | usr1   |        30 | True     |                                        |
    +-----------+------------------+-------------+--------+-----------+----------+----------------------------------------+

    pywbemcli> connection show
    name: Ronald (current)
      server: http://blah2
      mock-server:
      . . .

    pywbemcli> connection select testconn

    pywbemcli> connection list
    WBEM server connections: (#: default, *: current)
    +-----------+------------------+-------------+--------+-----------+----------+----------------------------------------+
    | name      | server           | namespace   | user   |   timeout | verify   | mock-server                            |
    |-----------+------------------+-------------+--------+-----------+----------+----------------------------------------|
    | Ronald    | http://blah2     | root/cimv2  | you    |        30 | True     |                                        |
    | *testconn | http://localhost | root/cimv2  | usr1   |        30 | True     |                                        |
    +-----------+------------------+-------------+--------+-----------+----------+----------------------------------------+

    pywbemcli> connection show
    name: testconn (current)
      server: http://localhost
      mock-server:
      . . .

    pywbemcli> connection show Ronald
    name: Ronald
      server: http://blah2
      mock-server:
      . . .

The concept of a current connection that can be selected is useful mostly for
the interactive mode. In command mode, the connection specified with one of the
``-server``, ``--mock-server``, or ``--name`` general options automatically is
considered the current connection, and there is no concept of selecting a
current connection other than using these options.
Therefore, pywbemcli additionally supports the concept of a persisted default
connection.

The following example defines a persisted default connection and then uses it in
command mode:

.. code-block:: text

    $ pywbemcli connection select Ronald --default
    "Ronald" default and current

    $ pywbemcli connection list
    WBEM server connections: (#: default, *: current)
    +-----------+------------------+-------------+--------+-----------+----------+----------------------------------------+
    | name      | server           | namespace   | user   |   timeout | verify   | mock-server                            |
    |-----------+------------------+-------------+--------+-----------+----------+----------------------------------------|
    | #Ronald   | http://blah2     | root/cimv2  | you    |        30 | True     |                                        |
    | testconn  | http://localhost | root/cimv2  | usr1   |        30 | True     |                                        |
    +-----------+------------------+-------------+--------+-----------+----------+----------------------------------------+

    $ pywbemcli connection show
    name: Ronald (default, current)
      server: http://blah2
      mock-server:
      . . .

Connections can be deleted with the ``connection delete`` command either with
the command argument containing the connection name or with no name provided so
pywbemcli presents a list of connections to choose from:

.. code-block:: text

    $ pywbemcli connection delete Ronald
    Deleted default connection "Ronald".

or:

.. code-block:: text

    $ pywbemcli connection delete
    Select a connection or CTRL_C to abort.
    0: Ronald
    1: testconn
    Input integer between 0 and 1 or Ctrl-C to exit selection: 0
    Deleted default connection "Ronald".
