.. highlight:: bat
.. _dpbuddyCLI:

DPBuddy's 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

You can specify the default value for any common option in a configuration file. The configuration file should have the properties (name=value) format. For example, to specify a DataPower user used to connect to DataPower, define ``dp.username=<my username>`` property in the configuration file.  Note that the name of the property could be different from the name of the option. Usually, properties have the ``dp.`` prefix. This is done for the sake of compatibility with Ant property names.

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

* If the ``-configFile`` command-line option is specified, DPBuddy will use the value of this option as the path to the configuration file.
* If the ``DPBUDDY_CONFIG`` environment variable is specified, DPBuddy will use the value of this variable as the path to the configuration file.
* DPBuddy will attempt to load the file ``dpbuddy.properties`` from the current directory (the directory where the command is run).
* DPBuddy will attempt to load the file ``dpbuddy.properties`` from the user's home directory using the path ``<home>/.dpbuddy/dpbuddy.properties``.

If the configuration file was not found, DPBuddy will print a warning message.

DPBuddy uses `Apache Commons Configuration <http://commons.apache.org/proper/commons-configuration>`_ to parse the 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 `"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.

We recommend using the prefix-based :ref:`property resolution mechanism <managing_env_vars>` which allows you to prefix all environment-dependent properties with the appropriate environment/device/domain prefixes. You can then point DPBuddy to a specific environment using the ``-env`` option:

.. code-block:: bat

   dpbuddy import -file domain.zip -env dev