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

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:

dpbuddy import -file domain.zip -dry-run

This is equivalent to:

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

You can also provide explicit false value:

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 Common Attributes/Options and Properties. For example, to specify a DataPower domain, you can run the import command with the -domain option:

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

You can specify the default value for any common option in a configuration file. In addition, configuration file can contain environment-dependent values. DPBuddy supports two different formats for defining configuration: HOCON 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 to parse the properties configuration file. Commons Configuration’s format supports many advanced features, including 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:

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 and Java system properties, so any of these properties can be used on the command line or in the configuration file:

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:

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

You can also split your DPBuddy configuration into multiple files and use HOCON includes or property files 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 environments are defined, you can point DPBuddy to a specific environment using the -env option:

dpbuddy import -file domain.zip -env dev

You can also use the 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.