This topic describes the
ectool command line interface to script CloudBees CD/RO operations, including access to the Perl API.
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 --helpdisplays a summary of all commands and other command-line options.
ectool --help <command>returns information about
<command>. For example,
ectool --help modifyStepreturns information about the
For a list of all
ectool commands, see Perl API commands overview
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, see the example below, which includes the server name, user name, and password.
ectool --server bldg1server login "Ellen Ernst" "ee123"
General syntax for ectool command usage:
ectool [global argument] <command> <positional arguments> [named arguments]
See Common global options for more information.
ectool CLI does not support any argument value that begins with a
-- (double hyphen), because this is reserved as the prefix for argument names.
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.
ectool addUsersToGroup group1 --userNames user1 user2 user3
name/value pairs: each pair is specified as a separate argument in the form name=value.
ectool runProcedure proj1 --procedureName proc1 --actualParameter parm1=value1 parm2=value2
Global arguments can be used alone or in conjunction with other commands. These arguments are used to control communication with the server.
Display an online version of
The CloudBees CD/RO server address. The default is the
Do not use in a step context: steps running
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.
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
HTTP listener port on the CloudBees CD/RO server. Defaults to port 8000.
HTTPS listener port on the CloudBees CD/RO server. Defaults to port 8443.
Use HTTPS to communicate with the CloudBees CD/RO server. Defaults to
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
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
Retry the request if it times out based on the "timeout" value. The default is "0" and should rarely need to be changed.
Use the session associated with the user. Defaults to the user who last logged in.
Specify the service principal name to use for Kerberos. Defaults to
Use the current session as the default for subsequent invocations. Defaults to
Use the specified encoding for input/output. For example, for
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
Suppresses printing the result. For example:
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
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
Specifies the response format. Must be one of 'xml' or 'json'. Defaults to 'xml'. For example, you might specify:
Force ectool to ignore