Use the CloudBees CD/RO ectool API

This topic describes the ectool command line interface to script CloudBees CD/RO operations, including access to the Perl API.

Use ectool

The ectool is a command line interface that provides operational control over the CloudBees CD/RO system. It supports a large collection of commands, each of which translates to a message sent to the CloudBees CD/RO server. For example, ectool getProjects returns information about all projects defined on the server.

ectool --help displays a summary of all commands and other command-line options.
ectool --help <command> returns information about <command>. For example, ectool --help modifyStep returns information about the modifyStep command.

For a list of all ectool commands, refer to Perl API commands overview.

IPV6 Compatibility

As of CloudBees CD/RO version 2024.03, `ectool supports the following IPv6 communications formats:

Standalone IPv6 address:, 2001:DB8:: or [2001:DB8::]
Combinations of IPv6 address and port: . [2001:DB8::]:443.

Sign in

If you use the ectool outside of a job, you must invoke the ectool login command to sign in to the CloudBees CD/RO server for all commands except getServerStatus. After signing in, ectool saves information about the login session for use in future ectool invocations. If you run ectool as part of a CloudBees CD/RO job, you do not need to sign in; ectool uses the login session (and credentials) for that job.

To sign in to a specific server, refer to the example below, which includes the server name, user name, and password.

ectool --server bldg1server login "Ellen Ernst" "ee123"▼

If your password is not as part of the login command, then you will be prompted to provide it.

General syntax for ectool command usage:

ectool [global argument] <command> <positional arguments> [named arguments]▼

Global arguments (optional)

Refer to Common global options for more information.

Character restrictions in arguments

The ectool CLI does not support any argument value that begins with a -- (double hyphen), because this is reserved as the prefix for argument names.

Pass lists as arguments

Some API commands include arguments that expect a list of values in one of two list forms: value lists and name/value pairs.

value list: each value is specified as a separate argument on the command line.

Example:
```
ectool addUsersToGroup group1 --userNames user1 user2 user3▼
```

name/value pairs: each pair is specified as a separate argument in the form name=value.

Example:

ectool runProcedure proj1 --procedureName proc1 --actualParameter parm1=value1 parm2=value2▼

Global environment variables

Global environment variables allow you to invoke ectool commands without specifying global flags, such as --server <serverName>, at the command line. Like global flags, these environment variables provide the context for evaluating ectool commands. For example, if the command ectool getProperty /myJob/outcome is run in a job step, then a value of the outcome property for that job step is returned. Global environment variables also provide ectool with a session that includes all user privileges associated with the job.

If the resource is a proxy agent, global environment variables are available in the step’s environment on the proxy target. For more information, refer to Configure agent environment variables.

Table 1. Environment variables
Variable	Description
`COMMANDER_ARTIFACT_CACHE`	The default directory location for storing artifacts retrieved with the `getArtifactVersions` API.
`COMMANDER_DATA`	A variable whose value is the data directory for an agent. On Windows, this directory is typically `C:\Program Files\CloudBees\Software Delivery Automation`. On UNIX platforms, this directory is typically `/opt/cloudbees/sda/`. This directory includes configuration and workspace files and directories.
`COMMANDER_HOME`	A variable whose value is the base installation directory for an agent. On Windows, this directory is typically `C:\Program Files\CloudBees\Software Delivery Automation`. On UNIX platforms, this directory is typically `/opt/cloudbees/sda/`.
`COMMANDER_HTTP_PROXY`	The port number for insecure communication with the CloudBees CD/RO server.
`COMMANDER_HTTPS_PORT`	The port number for secure communication with the CloudBees CD/RO server.
`COMMANDER_INITIAL_DELAY_BETWEEN_RETRIES_FOR_RETRIEVE_ARTIFACT`	The initial delay in milliseconds between retries when doing artifact retrieval using backing off algorithm. The delay default is 100 ms. For more information, refer to Retrieving artifact versions.
`COMMANDER_JOBID`	The unique identifier for the job containing the current job step.
`COMMANDER_JOBSTEPID`	The unique identifier for this job step.
`COMMANDER_MAXIMUM_DELAY_BETWEEN_RETRIES_FOR_RETRIEVE_ARTIFACT`	The Maximum delay in millisecond between retries when doing artifact retrieval using backing off algorithm. The maximum delay between retries defaults to 30000 ms. For more information, refer to Retrieving artifact versions.
`COMMANDER_NUMBER_OF_RETRIES_FOR_RETRIEVE_ARTIFACT`	The number of retry attempts for failing retrieveArtifactVersions API calls. The default number of retries is three. For more information, refer to Retrieving artifact versions.
`COMMANDER_PLUGINS`	(Configurable) The directory for installed plugins. For example, `C:\Documents and Settings\All Users\Application Data\CloudBees\Software Delivery Automation\Plugins`.
`COMMANDER_PORT`	The port number for normal communication with the CloudBees CD/RO server.
`COMMANDER_RESOURCENAME`	The resource name assigned to the job step.
`COMMANDER_SERVER`	The hostname or IP address of the CloudBees CD/RO server.
`COMMANDER_SESSIONID`	The current job’s CloudBees CD/RO session identifier, which allows ectool to access the CloudBees CD/RO with job associated privileges without an additional login.
`COMMANDER_WORKSPACE`	Absolute path suitable for accessing the top-level workspace directory for this job on this machine. On a UNIX machine, this has the same value as `COMMANDER_WORKSPACE_UNIX`. For Windows, it is the same as `COMMANDER_WORKSPACE_WINUNC`.
`COMMANDER_WORKSPACE_NAME`	This is the name of the workspace on the CloudBees CD/RO server.
`COMMANDER_WORKSPACE_UNIX`	The absolute Unix path to the workspace directory for this job.
`COMMANDER_WORKSPACE_WINDRIVE`	The absolute Windows path to the workspace directory for this job. Path begins with the drive letter.
`COMMANDER_WORKSPACE_WINUNC`	The absolute Windows UNC path to the workspace directory for this job.

Common global options

Global arguments can be used alone or in conjunction with other commands. These arguments are used to control communication with the server.

Global Arguments Description

--help

Display an online version of ectool commands with a short description. Display command information if followed by a command name.

--version

Display the ectool version number.

--server <hostname>

The CloudBees CD/RO server address. The default is the COMMANDER_SERVER environment variable. If this variable does not exist, the default falls to the last server contacted through the API. However, if there is no record for which server was contacted, the default is to localhost.

If you are using multiple servers, use the server option to ensure the correct server is specified for your task. For example, if you are using the import command, the server option may be particularly important.

Do not use in a step context: steps running ectool should never provide the server option if the intention is to communicate with the server that launched the step. If the intention is to communicate with a different server, this agent must be a registered, enabled resource in the second server. Thus, that server will ping the agent, and the agent will learn how to communicate with that server.

In a step context, the Perl API proxy server requests through the step’s agent. If the agent does not recognize the provided server-name, it rejects the request. ectool retries the operation because at some point the server should ping the agent, and then the agent will have learned how to communicate with the server.

Generally, the issue is that the server publicizes its name as a fully-qualified domain name and the Perl API issues requests with a simple-name for the server. This can happen if the step explicitly states which server it is connecting to. Fix your steps that invoke ectool so it no longer includes the server-name, and ectool defaults to the server-name that the server provided.

--port <port>

HTTP listener port on the CloudBees CD/RO server. Defaults to port 8000. Use with the COMMANDER_HTTP_PORT environment variable.

--securePort <secureport>

HTTPS listener port on the CloudBees CD/RO server. Defaults to port 8443. Use with the COMMANDER_HTTPS_PORT environment variable.

--secure <0|1>

Use HTTPS to communicate with the CloudBees CD/RO server. Defaults to 1.

Certain requests (for example, login, createUser, and modifyUser ) automatically use HTTPS because passwords are being sent, which means it is not necessary to specify secure for those APIs.

--timeout <s>

An API call waits for a response from the server for a specified amount of time. Timeout for server communication defaults to 180 seconds (3 minutes) if no other time is specified. After the timeout, the API call stops waiting for a response, but the server continues to process the command.

You can also use the global CloudBees CD/RO COMMANDER_ECTOOL_TIMEOUT environment variable. The --timeout <s> argument overrides the value of this environment variable if it is set.

--retryTimeout <s>

This is a separate timer, independent of the retry flag, and is used to control CloudBees CD/RO automatic error recovery. When the API cannot contact the CloudBees CD/RO server, it keeps trying to contact the server for this length of time. When the API is called from inside a step, it defaults to 24 hours.

You can also use the global CloudBees CD/RO COMMANDER_ECTOOL_RETRY_TIMEOUT environment variable. The --retryTimeout <s> argument overrides the value of this environment variable if it is set.

--retry <0|1>

Retry the request if it times out based on the "timeout" value. The default is "0" and should rarely need to be changed.

--user <username>

Use the session associated with the user. Defaults to the user who last logged in.

--service <spn>

Specify the service principal name to use for Kerberos. Defaults to HTTP@host.domain.

--setDefault <0|1>

Use the current session as the default for subsequent invocations. Defaults to 1.

encoding <charEncoding>

Use the specified encoding for input/output. For example, for charEncoding, enter UTF-8, cp 437, and so on. The default is autodetected.

--dryrun

Displays session information and the request that would be sent, without communicating with the server. If a subcommand is specified, the server request that would be sent is displayed. This option can also be used to change the default user/server value by specifying the --user or --server options.

--silent

Suppresses printing the result. For example: ectool --silent createResource foo will not print the resource name, agent state, any modify information, create time, owner, port, or any other information otherwise displayed when you create a resource.

--suppressAdvisoryMessages

Suppress printing of advisory messages. By default, advisory messages, including those related to license and use of APIs that are deprecated or in preview mode, are logged on the console when invoked using ectool.

--valueOf

This option can return the value of a unique element. Because many ectool APIs return an XML result, it is inconvenient to use ectool in shell scripts and makefiles where you might want a piece of the ectool result to incorporate into some other logic. Using the --valueOf <path> option evaluates the XML result and emits the value of that node to satisfy such use cases. For example: $ ectool --valueOf '//version' getServerStatus returns only "4.1.0.48418".

--format <format>

Specifies the response format. Must be one of 'xml' or 'json'. Defaults to 'xml'. For example, you might specify: ectool --format json setProperty summary hello

--ignoreEnvironment

Force ectool to ignore COMMANDER_ENV variables.

Use ectool to allow web servers to proxy incoming application server requests

You can configure and execute ectool commands to allow the Apache web server to proxy incoming access to the CloudBees CD/RO application server. These requests occur even when server ports (8000/8443) are not available externally.

Outgoing or incoming requests to other CloudBees CD/RO components are not supported.

Enter the following to modify the server and securePort arguments to specify the Apache web server address.

  $ ectool --server localhost --securePort 443 login admin changeme
<response requestId="1" nodeId="192.168.56.3">
    <sessionId>YQELTIOXWK57IRPO</sessionId>
    <userName>admin</userName>
  </response>
$
ectool getVersions
<response requestId="1" nodeId="192.168.56.3">
    <serverVersion>
      <label>build_10.5_154796_2022.05.23_03:10:48</label>
      <protocolVersion>2.3</protocolVersion>
      <schemaVersion>108</schemaVersion>
      <version>10.5.1.154796</version>
    </serverVersion>
  </response>▼