Jenkins CLI tool

Jenkins CLI gives you command-line tools to manage operations center jobs or projects as well as agent- and administration-related activities.

The operations center’s Jenkins CLI feature (http://operations-center-url:port-number/cli) provides access to the Jenkins CLI tool (jenkins-cli.jar), which you can download from this URL. This page also provides detailed information about using this tool and its features.

Get the Jenkins CLI tool

To access the Jenkins CLI feature’s page through the operations center interface and download the CLI tool:

Access the Manage Jenkins area.
On the Manage Jenkins page, scroll down and select Jenkins CLI.
On the Jenkins CLI page, select the jenkins-cli.jar link to download the CLI tool.
Move the jenkins-cli.jar file to an appropriate location on your machine’s file system.

Use the Jenkins CLI tool

In a terminal window, change to the directory containing the jenkins-cli.jar file:

java -jar jenkins-cli.jar -s http://operations-center-url:port-number/ command▼

Where:

operations-center-url is the URL of the operations center.
port-number is the HTTP port through which operations center is accessible.
command is the Jenkins CLI command you want to execute.

To obtain a list of all options (like -s above or -auth for authentication) that can be passed to the jenkins-cli.jar command itself, enter the command:

java -jar jenkins-cli.jar -h▼

Examples of usage

This section provides common examples of usage:

List all available Jenkins CLI tool commands
Authenticate users with the Jenkins CLI tool
Obtain information about Jenkins CLI tool commands

Be sure to replace operations-center-url with the URL of the operations center.

List all available Jenkins CLI tool commands

Type the following command to list all available Jenkins CLI tool commands:

java -jar jenkins-cli.jar -s https://operations-center-url:8888/ help▼

This outputs a list of commands followed by indented descriptions, such as:

add-job-to-view
  Adds jobs to view.
...▼

Authenticate users with the Jenkins CLI tool

To authenticate your Jenkins user when using the Jenkins CLI tool, specify the -auth option with your username and API token in the following format: username:apiToken.

Many Jenkins CLI commands require an authenticated Jenkins user with appropriate permissions, such as the Administer permission. For more on permissions in CloudBees CI, refer to Restricting access and delegating administration with Role-Based Access Control.

For example, enter the command:

java -jar jenkins-cli.jar -auth username:apiToken -s https://operations-center-url:8888/ version▼

The resulting output contains a version number:

2.375.3.5▼

Obtain information about Jenkins CLI tool commands

To obtain more information about a particular Jenkins CLI command, specify help followed by the command itself.

For example, to obtain more information about the plugin-catalog command, enter the command:

java -jar jenkins-cli.jar -auth username:apiToken -s https://operations-center-url:8888/ help plugin-catalog▼

The following output is displayed:

java -jar jenkins-cli.jar plugin-catalog [VAL] [--delete VAL] [--master VAL] [--push VAL] [--put] [--remove VAL]
Plugin Catalog Management
 VAL          : Use a catalog name to get its metadata content. A list of
                catalog names is returned by calling the command without any
                parameter.
                plugin-catalog
                plugin-catalog my-plugin-catalog
 --delete VAL : Use this option to delete a catalog from the available list,
                whose name is passed as parameter.
                --delete my-plugin-catalog
 --master VAL : Master item full name (including folders and white spaces,
                which needs double quotes). Use it in tandem with --push to
                select the master to push the catalog to.
                --master my-controller --push my-plugin-catalog
 --push VAL   : This option pushes a catalog to a master. Use it in tandem with
                --master to select the master to apply the catalog to.
                --master my-master --push my-plugin-catalog
 --put        : Create or update a catalog. It will not be applied to any
                master, just added to the catalog management.
                --put < my-plugin-catalog.json
 --remove VAL : Removes the current catalog from a master. The catalog will not
                be deleted from the available list.
                --remove my-master-with-a-plugin-catalog▼