About the Command Line Interface (CLI)

The Business Transaction Management Command Line Interface (CLI) allows you to issue management commands from the command line or through the use of scripts (in bash, perl, ruby, DOS). You can use the CLI from the Unix and DOS command lines, and any other environments that work with your Business Transaction Management installation.

CLI commands allow you to configure the system, manage DNS aliases, resolve replication issues, register services, manage metadata, control monitoring, apply policies, migrate data, or generate data needed for reporting.

The CLI executable (btmcli.bat on Windows and btmcli.sh on Unix-like systems) is located in the BTM_Install_Directory/tools directory. On Windows platforms, the CLI uses the JRE bundled with Business Transaction Management. On Unix-like systems, you must specify a JRE to use by doing one of the following:

  • set the JAVA_HOME environment variable and remove the BTMi_nstall_dir/_server/jre directory

  • replace BTM_install_dir/server/jre with a link to a valid JRE directory

There are several command line utilities for performing additional actions. See About Command Line Utilities for more information.

Getting Help and Version Information

To get a list of all CLI commands with a brief help summary, enter the following command:

C: > btmcli help

To get detailed help for an individual command, enter a command like the following:

C: > btmcli help commandName

To get version information, use the following command:

C: > btmcli -v

Executing CLI Commands and Scripts

You can execute a Business Transaction Management CLI command or script in any command shell using the following syntax:

btmcli commandName commandFlags

To execute a single command, specify the command and its parameters at the command prompt. For example:

C: btmcli encryptPassword -password "abracadabra"

To execute a script, specify the name of the script at the command prompt. For example:

C: > myBTMScript.cmd
  • The script can contain any Business Transaction Management CLI commands.

  • The name of your script file should have an extension that is appropriate for your operating system (.cmd, .bat, .sh).

  • Script comments should be formatted as appropriate for your operating system.

  • The script can make use of the environment variables described in Environment Variables.

Security Options in Accessing CLI Commands

Nearly all CLI commands require that you provide a credential in the form of username:password to execute the command.

You can provide this credential in one of two ways:

  • Using the -l flag to the command.

  • Setting the AP_USER_LOGIN environment variable to the value of the credential. In this case, you do not have to specify the -l flag.

Whether you use the -l flag or the environment variable, you can specify the credential in one of two ways:

  • by providing the user name and password directly when you enter the command, or by setting the AP_USER_LOGIN environment variable to that username:password value.

  • by creating a username:password credential in a credential store, and passing the credential name to the command or by setting the AP_USER_LOGIN environment variable to the value of that credential name.

The following examples use the btmcli configure command to illustrate each case:

  1. In the following command, the -l flag is used to specify a user name and password.

    btmcli configure -i myConfigureFile -s http://uitst3:8080/btmcentral/sphere/
    -l joanna:abracadabra
  2. In the following command, no -l flag is specified because the AP_USER_LOGIN environment variable has been set to joanna:abracadabra.

    btmcli configure -i myConfigureFile -s http://uitst3:8080/btmcentral/sphere
  3. In the following command, the credential JoannaCred has been defined by the credStoreTool command as follows:

    btmcli credStoreTool -createCred JoannaCred -credType up
    -credValue joanna:abracadabra

    The configure command will then look like this:

    btmcli configure -i myConfigureFile -s http://uitst3:8080/btmcentral/sphere/
    -l JoannaCred
  4. In the following command, the credential JoannaCred has been defined by the credStoreTool command as follows:

    btmcli credStoreTool -createCred JoannaCred -credType up
    -credValue joanna:abracadabra

    The AP_USER_LOGIN environment variable has then been set to JoannaCred=joanna:abracadabra. The configure command will then look like this:

    btmcli configure -i myConfigureFile -s http://uitst3:8080/btmcentral/sphere/

Command Summary

The following table lists CLI commands in alphabetical order and provides a summary of the command action.

Command Name Description
addBaseAddressAlias Add the specified alias for the entry point with the given base address. If another entry point with this alias as its base address is already known to the sphere, the two entry points and their contents are merged, and duplicate WSDLs and endpoints are removed.
addNodeAlias Add network aliases to an already registered node.
addPathAlias Use the addPathAlias command to add an alias representing an alternative URL path that can be used to access the specified WSDL or endpoint. Specifying this alias can help prevent duplicate artifacts from being created during discovery.
configure Read a configuration xml file and use the information to configure the installation associated with the given sphere URL.
configureAlivenessCheck Specify the preferred method for the sphere to check the aliveness of endpoints, rather than using the default ping.
createOrUpdateGenre Specifies the name of a new service or endpoint genre, and identifies a custom icon to be used in representing the new genre.
createOrUpdatePolicy Create or update the specified policy directly in the sphere.
createSettingsDocument Use the createSettingsDocument command to create a settings document for input to the createOrUpdatePolicy command.
credStoreTool Creates, obtains, or deletes the specified type of credential from the credential store.
encryptPassword Convert the specified text string using the Business Transaction Management encryption engine. The resulting cipher text appears in the command output.
exportBusinessObjects Create a settings document for input to the createOrUpdatePolicy command.
exportMessages Export messages for an endpoint for a specified period of time. Exporting messages can be useful in testing and debugging.

You have the option of exporting messages to a file; whether you do or not, output is always sent to the Console.

exportPolicies Export the specified policies either to stdout, or to the named output file. Policies can be exported by name, type, or by means of a query that defines a set of policies.
exportPolicyTemplates Export the specified policy templates either to stdout, or to the named output file. Policies templates can be exported by name, type, or by means of a query that defines a set of policies.
exportProfile Export the profile values for the specified object(s) either to stdout, or to the named output file. Profiles can be exported by name or id.
exportSchedules Export schedules from the target sphere. You can output the schedules to a file or to stdout. Schedules can be exported by name or by means of a query that defines a set of policies.
exportTransactionDefns Export the specified transaction definitions. If you do not specify an output file, the definition is sent to stdout.
generateMonitoringScript Generate a batch script that you can use later to recreate the system's current monitoring state.
getSetupData Write the setup file for the specified service to standard output. You can use this setup file as input for the putSetupData command.
importBusinessObjects Import one or more of the specified business objects described by the specified XML file into the target sphere. By default, this command replaces all existing objects that are older than the imported objects.
importPolicies Import the policies contained in a previously created export file. The policies to be imported will be taken from the file specified by the -i parameter, or from stdin, if no such file is specified.
importPolicyTemplates Import the policy templates contained in a previously created export file. The policy templates to be imported will be taken from the file provided by the -i parameter or from stdin if no such file is specified.
importProfile Import a previously exported object profile into the system. Note that importing a profile does not cause new objects to be created, it only updates the profile attributes of existing objects.
importSchedules Import previously exported schedules to the target sphere. By default, this command replaces all existing schedules that are older than imported schedules.
importTransactionDefns Import previously exported transaction definitions to the specified sphere. By default, this command replaces all existing definitions that are older than imported definitions.
listInstruments List the instruments defined by the policy templates in the system, as well as the attribute names and segments for each. You can use this information as arguments for the retrieveObjectData command.
listNodeAliases List all the aliases for a single network node, or for all known network nodes.
mergeServices Merge two versions of the specified service. This command removes the source version and moves its endpoints to the target version.

After the merge, the target version contains all the endpoints from both versions. If the source version has any profile attributes or message properties that you want to retain for the merged versions, you must recreate these on the target version.

monitorEndpoint Monitor the specified endpoint with the monitor agent where it is registered.
moveEndpoints Move one or more endpoints from the source version to the target version of the specified service.
moveMeasurements Move the measurements collected for a service or endpoint that has been deleted from the sphere to another endpoint or service that is its logical successor.
putSetupData Read the setup file from a named file or from standard input and save it as the setup data for the specified service.
register Register the services (found within the specified WSDL file) with the sphere and write the location URLs of the WSDL's service endpoints to standard output. This command produces the same output if the WSDL is already registered with the sphere.
registerDevice Register a management device with the sphere. Currently, hardware and software load balancers are the only supported device type, and the F5 BigIP is the only fully-supported load-balancer.

If you register multiple devices, you can use the setDefaultLoadBalancer command to set the default device.

registerExternalContainer Group the endpoints of one or more entry points (not part of an observed container) into their own external container. This is only necessary for manually-registered endpoints.
registerMonitor Register a monitor agent with Business Transaction Management.
removeBaseAddressAlias Remove the specified alias to the entry point with the given base address. The alias must be defined locally for this entry point only. Aliases defined at the network node level must be removed using the removeNodeAlias command.
removeDuplicateEndpoint Remove the specified duplicate endpoint. Typically, you would use this command when the system discovers two endpoints with the same path but different host names due to a DNS alias that was not known to the system. Executing this command also adds the missing alias to make sure that future discoveries do not result in recreating the duplicate endpoint.
removeNode Remove a network node from the sphere.
removeNodeAlias Remove aliases from a registered node.
removePathAlias Remove an alias representing an alternative URL path that can be used to access the specified WSDL or endpoint. Any future registration or discovery will again treat the two paths as distinct.
removePolicy Remove an applied policy and optionally wait for the removal of the policy to complete.
removePolicyTemplate Removes the specified policy template from the system.
renameEndpoint Change the specified endpoint's friendly name in the sphere.
resetSphereUrl Make sure the sphere URL for container services currently registered with this sphere matches the current sphere URL. You might need to use this command if the base address of the sphere changes.
retrieveObjectData Retrieve profile and measurement data for one or more objects. You can use this data as input to a reporting tool.
sendEventNotification Create and send an event notification using the Notifier Service. How the notification is handled is determined by the currently active subscriptions.
sendToNotifier Send commands to the Notifier Service for processing. The commands are specified in the XML input file. The command returns the response document returned by the Notifier Service.
setBaselines Set baselines for managed objects. The input document format is the same as the output of the retrieveObjectData command.
setDefaultLoadBalancer Set the default device used to model routing entry points discovered from observed message traffic.

In a simple environment with only one known load-balancer, that device is automatically used as the default. If you register additional devices, use this command to set which device should be used to model routing entry points.

showService Show the structure of the service specified by the friendly name, qualified name, or URL of any endpoint for this service. You can also specify a single version of the service (-version) or the display of more detailed information (-verbose).
unmonitorEndpoint Stop monitoring the specified endpoint with the monitor agent where it is registered. Once monitoring stops, no performance measurements are recorded, no messages are logged, and no transactions are traced.
unregister Unregister the service, WSDL, or endpoint from the sphere.
unregisterContainer Unregisters the specified container.
unregisterMonitor Unregister the specified monitor agent from the sphere. Use this command only when the monitor has been taken offline permanently. Monitors must be offline long enough for the system to mark them down before you can unregister them.
updateProfileData Update profile attribute data for the specified set of objects. This command only updates existing objects; if it cannot find the specified objects, it returns an error.

Environment Variables

The following table describes environment variables that you can define for use with the Business Transaction Management commands in the place of commonly used command flags.

Environment Variable Flag Name Equivalen Flag Long Name Equivalent Description
AP_SPHERE_URL -s -sphereUrl The URL for the sphere. http://hostname:port/apcentral/sphere/

.NET example: http://host:port/apcentral/sphere/soa.asmx

AP_USER_LOGIN -l -userLogin The log-in credentials for the sphere, in one of the following formats:



Typically these would be the credentials of a user with administrative privileges.

See Authentication and Role Mapping for more information.

You can encrypt passwords for use with the CLI using the encryptPassword command.

Attribute Names

A number of CLI commands require that you pass an attribute name as a flag value. This section lists valid attribute names for different object types.

Endpoint Attributes

Name Name Name
aliases friendlyName operationsNote
binding gateway qualifiedName
businessContact genericNote relativeLocation
businessNote genre service
contact interface serviceQName
container isAlive relativeLocation
defaultCredentials lastIsAliveChangeDate service
dependsOnEndpoint lastManagementChangeDate serviceQName
deployment lastManagementChangeIdentity serviceDescriptionURL
description lastUpdateIdentity supportContact
endpointAppProtocol lastUpdateMarker supportNote
endpointSoftwareType location targetEndpoint
endpointSource managingIntermediaries technicalContact
endpointTransportProtocol note technicalNote
endpointType operations testingNote
firstRegistryDate operationsContact uddiBusinessKey
-- -- uddiKey

Operation Attributes


Interface Attributes

Name Name Name
businessContact name supportNote
businessNote namespace technicalContact
classifications note technicalNote
contact operations testingNote
description operationsContact uddiBusinessKey
friendlyName operationsNote uddiKey
genericNote owningEndpoint --
lastUpdateIdentity sourceType --
lastUpdateMarker supportContact --

Interface Operation Attributes


Service Attributes

Name Name Name
alive lastIsAliveChangeDate serviceSource
applicationGroup lastManagementChangeDate serviceType
businessContact lastManagementChangeIdentity supportContact
businessNote lastUpdateIdentity supportNote
category lastUpdateMarker technicalContact
contact managedDescriptionURL technicalNote
deploymentNames note testingContact
description operations testingNote
documentation operationsContact uddiBusinessKey
endpoints operationsNote uddiKey
firstRegistryDate organization version
friendlyName originalDescriptionURL --
lastDeployDate primaryDeploymentName --
lastDeployIdentity qualifiedName --

Transaction Attributes

The only transaction attribute is friendlyName.

Container Attributes

Name Name Name
administratorUI lastIsAliveChangeDate phaseInLifeCycle
baseAddress lastDeployIdentity supportContact
businessContact lastDiscoveryDate supportNote
businessNote lastManagementChangeDate technicalContact
connectionLimit lastManagementChangeIdentity technicalNote
contact lastUpdateIdentity testingContact
containerInfo lastUpdateMarker testingNote
firstRegistryDate note uddiBusinessKey
friendlyName operationsContact uddiKey
genericNote operationsNote --
hostName osName --
implementationType osVersion --
ipAddress owner --
isAlive performanceRating --

Deployment Attributes

Name Name Name
businessContact isAlive supportContact
businessNote lastDeploymentDate supportNote
contact lastDeploymentIdentity technicalContact
container lastIsAliveChangeDate technicalNote
deploymentCategory lastUpdateIdentity testingContact
deploymentStatus lastUpdateMarker testingNote
deploymentType note uddiBusinessKey
description operationsContact uddiKey
firstRegistryDate operationsNote --
friendlyName pluginAgentPossible --
genericNote pluginAgentPossibleText --

Contact Identity Attributes


Notes Type Attributes

Includes two attribute names: theNote and usage.

Description Attributes

Includes two attribute names: contacts and notes.