Using the Perl API
IntroductionAccess tokensACL managementApplication dependencyApplicationsApplication tier Artifact managementCatalogsChange historyCI build detailCI configurationCI jobsComponentsCredential managementCustom filtersDatabase configurationData retentionCloudBees AnalyticsDirectory provider managementDynamic environmentsEmail configuration managementEmail notifier managementEnvironmentEnvironment tierGateway and zone managementInstalling or upgrading remote agentsJob managementMicroservicesObject tagsParameter managementPersonasPipelines and releasesPlugin managementPlugin configuration managementProcedure managementProcessProcess dependencyProcess stepProject managementProperty managementResource managementRolling deploySchedule managementService accounts for webhooksServer managementSingle sign on for SAMLSnapshotsTier mapTrigger managementUser and group managementUser profile email managementWait dependenciesWorkflow definition managementWorkflow managementWork itemsWorkspace managementMiscellaneous management
Perl API response and element glossary
IntroductionExamplesTroubleshooting
IntroductionaccesstokenaclaclentryactualparameteractualparametersapplicationapplicationdependencyapplicationtierarchiveconnectorartifactartifactversioncatalogcatalogitemcatalogitemruncibuildcibuilddetailciconfigurationcieventclustercomponentcredentialcredentialproviderdashboarddashboardcolumndataretentionpolicydeployerapplicationdeployerconfigurationdeploymenthistoryitemdevopsinsightdatasourcedirectoryprovideremailconfigemailnotifierentitychangeenvironmentenvironmentinventoryitemenvironmenttemplateenvironmenttemplatetierenvironmenttemplatetiermapenvironmenttemplatetiermappingenvironmenttierenvtempltierresourcetemplmappingeventsubscriptionflowruntimeformaloutputparameterformalparametergategatewaygrouphookjobjobstepkerberoskeytablicensemicroservicemicroservicemappingnoteobjectopenidconnectconfigurationoutputparameterpersonapersonacategorypersonapagepipelinepluginplugincatalogpluginconfigurationprocedureprocedurestepprocessprocessdependencyprocessstepprojectpropertyreleasereportreportingfilterreportobjectassociationreportobjectattributereportobjecttyperepositoryreservationresourceresourcepoolresourcetemplateresourceusageretrievedartifactsrollingdeployphaserundiscoverysamlidentityprovidersamlserviceproviderschedulescmsyncsearchfilterserverserversettingserversettingcategoryserviceaccountsessionsnapshotstagestatestatedefinitiontagtasktiermaptiermappingtransitiontransitiondefinitiontriggertriggererrordetailuseruseremailutilityresourcewaitdependencywebhookresultwidgetwidgetfilteroverrideworkflowworkflowdefinitionworkitemworkspacezoneArgument models

CloudBees CD/RO command line access

5 minute readReferenceDeveloper productivity

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

Using 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, see Perl API commands overview.

Signing 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, 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]
▼

Global arguments (optional)

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

Passing 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
    ▼

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.

--securePort <secureport>

HTTPS listener port on the CloudBees CD/RO server. Defaults to port 8443.

--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.
API error messages