3. 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

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. 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 to parse the 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 “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 property resolution mechanism 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:

dpbuddy import -file domain.zip -env dev