.. highlight:: bat
.. _dpbuddyCLI:

Command-Line Interface (CLI)
============================

All DPBuddy commands have the following format::

   dpbuddy <command> <options>

"command" is any of the commands/tasks described in the document. The command (or ``-h``) must be the first argument.

In this document the words "task" and "command" are used interchangeably. Every DPBuddy command has a corresponding Ant task with the same name.

The options for every command are listed under "Options/Attributes". Each option must be preceded by ``-``.  In this document, "option" and "attribute" are also used interchangeably; every command line option has a corresponding Ant attribute and vice versa.
For example, the ``import`` command supports the ``file`` option. To run the command, type

.. code-block:: bat

   dpbuddy import -file domain.zip

The value is optional for Boolean options. The Boolean options always default to ``true``. For example, to run ``import`` in the dry-run mode, supply ``-dry-run`` option:

.. code-block:: bat

   dpbuddy import -file domain.zip -dry-run

This is equivalent to:

.. code-block:: bat

   dpbuddy import -file domain.zip -dry-run true

You can also provide explicit ``false`` value:

.. code-block:: bat

   dpbuddy import -file domain.zip -dry-run false

All commands support the ``-h`` option, which displays the list of all supported options and their descriptions, e.g., ``dpbuddy import -h``.

There are several other options that are common to all DPBuddy commands. All these options are listed in :ref:`common_properties`. For example, to specify a DataPower domain, you can run the ``import`` command with the ``-domain`` option:

.. code-block:: bat

   dpbuddy import -file domain.zip -domain my-domain

.. _confFileCli:

You can specify the default value for any :ref:`common option<common_properties>` in a configuration file. In addition, configuration file can contain :ref:`environment-dependent values <managing_env_vars>`.
DPBuddy supports two different formats for defining configuration: :ref:`HOCON <hoconConfig>` and name=value properties. HOCON files have ".conf" extension and properties files have ".properties" extension. The default name of the configuration file is dpbuddy.conf or dpbuddy.properties.

DPBuddy follows these steps to locate and load the configuration file:

* If the ``-confFile`` command-line option is specified, DPBuddy will use the value of this option as the path to the configuration file. This is a full path that includes the name of the file.
* If the ``DPBUDDY_CONFIG`` environment variable is specified, DPBuddy will use the value of this variable as the path to the configuration file. This is a full path that includes the name of the file.
* DPBuddy will attempt to load the file ``dpbuddy.conf`` from the ``$DPBUDDY_HOME/conf`` directory.
* DPBuddy will attempt to load the file ``dpbuddy.conf`` from the current directory (the directory where the command is run).
* DPBuddy will attempt to load the file ``dpbuddy.conf`` from the user's home directory using the path ``<home>/.dpbuddy/dpbuddy.conf``.
* DPBuddy will attempt to load the file ``dpbuddy.conf`` from "/etc".
* If ``dpbuddy.conf`` is not found, DPBuddy will repeat the last three steps for name ``dpbuddy.properties``.
* If neither file is found, DPBuddy will print a warning message.

DPBuddy uses `Apache Commons Configuration <http://commons.apache.org/proper/commons-configuration>`_ to parse the properties configuration file. Commons Configuration's format supports many advanced features, including `variable interpolation <http://commons.apache.org/proper/commons-configuration/userguide/howto_basicfeatures.html#Variable_Interpolation>`_. This means that a property in the configuration file can reference another property's value using ``${}`` notation.

``${}`` can also be used directly on the command line as an option's value:

.. code-block:: bat

   dpbuddy import -file "\${import.file.path}"

In this example ``import.file.path`` is the property defined in the configuration file. Note that ``$`` must be escaped using ``\$`` on Linux to prevent the shell from treating it as a shell variable.

DPBuddy pre-populates all `built-in Ant properties <http://ant.apache.org/manual/properties.html>`_ and `Java system properties <http://docs.oracle.com/javase/7/docs/api/java/lang/System.html#getProperties%28%29>`_, so any of these properties can be used on the command line or in the configuration file:

.. code-block:: bat

   dpbuddy tailLog -lines "-1" -logFile "\${java.io.tmpdir}/dp.log" -appendTimestamp

You can also set properties using the environment variable ``DPBUDDY_OPTS`` and ``-D`` Java option:

.. code-block:: bat

   set DPBUDDY_OPTS=-Xmx1024m -Ddev.dp.host=myDPHost

You can also split your DPBuddy configuration into multiple files and use `HOCON includes <https://github.com/typesafehub/config/blob/master/HOCON.md#includes>`_ or  `property files includes <http://commons.apache.org/proper/commons-configuration/userguide/howto_properties.html#Includes>`_ to create a master file, e.g., ``include=another_config.properties``.

You can use the sample configuration file included in the distribution under ``samples/cli-shell`` and ``samples/cli-win`` as the starting point for your DPBuddy configuration file.

Once your configuration and your :ref:`environments <managing_env_vars>` are defined, you can point DPBuddy to a specific environment using the ``-env`` option:

.. code-block:: bat

   dpbuddy import -file domain.zip -env dev

You can also use the :ref:`exportConf` command to save configuration for a particular environment as a shell/batch file (i.e., each environment configuration property is translated into a shell variable). This file can then be sourced from other scripts thus providing convenient access to the environment configuration from any shell command.