Managing CloudBees Jenkins Enterprise 1.x

4 minute read
CloudBees will no longer be supporting CloudBees Jenkins Enterprise 1.x after July 30, 2020. This end-of-life announcement allows CloudBees to focus on driving new technology and product innovation for CloudBees CI. For information on moving to CloudBees CI, please refer to CloudBees Jenkins Enterprise 1.x to CloudBees CI on modern cloud platforms migration guide which has been created to help you with the migration process. Existing customers can also contact their CSM to help ensure a smooth transition.

This chapter describes how to manage your operations center instance for CloudBees Jenkins Enterprise 1.x.

Accessing Jenkins CLI

Jenkins CLI allows you to perform a number of activities on items (i.e. jobs or projects configured in your operations center instance), as well as agent- and administration-related activities on operations center, all from the command line.

The Jenkins CLI feature’s page (of the operations center interface) provides access to the Jenkins CLI tool (jenkins-cli.jar), which you can download from this page. This page also contains detailed information about using this tool and its features.

To access Jenkins CLI feature’s page and download the CLI tool:

  1. Access the Manage Jenkins area.

  2. On the Manage Jenkins page, scroll down and click Jenkins CLI.

  3. On the Jenkins CLI page, click the jenkins-cli.jar link to download the CLI tool near the top of this page.

  4. Move the jenkins-cli.jar file to an appropriate location on your operation system’s file system.

Using the Jenkins CLI Tool

Once you have obtained the Jenkins CLI tool (from the previous section), to use the CLI tool:

  1. In a terminal/command prompt (window), cd to the directory containing the jenkins-cli.jar file.

  2. Enter the command:

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


    • 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

    === Important examples of usage

    • To list all available Jenkins CLI tool commands, enter the command:

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

      which outputs a list of commands followed by indented descriptions, like:

        Adds jobs to view.
    • To authenticate your Jenkins user when using the Jenkins CLI tool, specify the -auth option with your username and password in the format: username:password.
      For example, enter the command:

      java -jar jenkins-cli.jar -auth username:password -s http://operations-center-url:8888/ version

      which outputs something like:

    Many Jenkins CLI commands require an authenticated Jenkins user with appropriate permissions, such as the Administer permission.

  • 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:password -s http://operations-center-url:8888/ help plugin-catalog

    which outputs:

    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
                    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-master --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

=== Configuring an Alias for the Jenkins CLI Tool

If you find yourself using the Jenkins CLI tool on a regular basis, configure an alias to save you having to write out the entire command each time.

For instance, assuming you are using on Linux operating systems and/or a Bash [1] command language environment:

  1. cd to the directory containing the jenkins-cli.jar file.

  2. In your favorite text editor, copy and paste the following into a new "alias" file:

    java -jar jenkins-cli.jar -auth username:password -s http://operations-center-url:port-number/ "$@"
  3. Adjust the username, password, operations-center-url and port-number values as required.

  4. Save the alias file with an appropriate file name (e.g.
    Note: This alias file assumes that jenkins-cli.jar is located in the same directory.

  5. Make the alias file executable (e.g. chmod a+x

  6. Configure the actual alias to your alias file in your appropriate Bash configuration file (i.e .bash_profile or .bashrc), which is usually located in your home directory.
    For example, in your favorite text editor, copy and paste the following line into .bash_profile or .bashrc):

    alias jenkins-cli='/path/to/'
  7. Edit the /path/to value as required and save the configuration file.

  8. Reload your Bash configuration by entering the appropriate command (based on the file you edited).
    For example, enter the appropriate command:

    • source ~/.bash_profile

    • source ~/.bashrc

From now on, regardless of your current directory, you can enter the command: jenkins-cli, which would actually be:

java -jar jenkins-cli.jar -auth username:password -s http://operations-center-url:port-number/

Therefore, using this alias, the important examples of usage (above) could be simplified to the following:

  • Listing all available Jenkins CLI tool commands:

    jenkins-cli help
  • Retrieving the version of your operations center instance:

    jenkins-cli version
  • Obtaining more information about a specific Jenkins CLI command:

    jenkins-cli help plugin-catalog
The remaining Jenkins CLI examples used throughout this guide assume that this alias has been configured.