Manage plugins from the command line

You can use the Jenkins CLI tool to manage plugins from the command line instead of via the Manage Plugins GUI.

This chapter describes how to manage plugins from the command line. To manage plugins from Operations Center or Client Masters, refer to Managing plugins.

Getting the 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.

To access the Jenkins CLI feature’s page through the Operations Center interface 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 machine’s file system.

Using the Jenkins CLI tool

Once you have obtained the Jenkins CLI tool as described in the previous section, to use the CLI tool:

  1. In a terminal/command prompt (window), change 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

    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. Be sure to replace operations-center-url with the URL of the Operations Center.

  • To list all available Jenkins CLI tool commands:

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

    which outputs a list of commands followed by indented descriptions such as

    add-job-to-view
      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

    The resulting output contains a version number:

    2.107.2.2
    Many Jenkins CLI commands require an authenticated Jenkins user with appropriate permissions, such as the Administer permission. For more on permissions in CloudBees Core, see Restricting access and delegating administration with Role-Based Access Control in CloudBees Core on modern cloud platforms.
  • 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
    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-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

From Client Masters

Jenkins allows some operations to be invoked through CLI, some of them being useful to configure Client Masters.

But also, when we are talking about Client Masters configuration, applying the same identical configuration to each one is something desirable. Thus we need a way to gather all connected masters from the command line and then perform some operations on each one.

The list-masters CLI command on Operations Center provides information about all connected masters in JSON format, allowing you to use that information to invoke commands on each Client Master:

{
  "version": "1",
  "data": {
    "masters": [
      {
        "fullName": "my master", (1)
        "url": "http://localhost:9090/", (2)
        "status": "ONLINE" (3)
      }
    ]
  }
}
1 fullName - the name of the Client Master, including folders.
2 url - URL for the Client Master.
3 status - the connection status of the Client Master. It can be 'ONLINE' or 'OFFLINE'.

Examples of usage

This section provides examples of CLI operations for Client Masters.

Execute a Groovy script and install a plugin

The following bash script will execute a Groovy script and install the 'beer' plugin on all the online Client Masters:

#!/usr/bin/env bash

JENKINS_CLI=jenkins-cli.jar
JENKINS_CJOC_URL=http://localhost:8080/
JENKINS_AUTH=admin:admin

if [ -z "$JENKINS_CJOC_URL" ]; then
    echo "Need to set environment variable JENKINS_CJOC_URL (Operations Center root URL)."
    exit 1
fi

if [ -z "$JENKINS_AUTH" ]; then
    echo "Need to set environment variable JENKINS_AUTH (format: 'userId:apiToken')."
    exit 1
fi


if [ -f "$JENKINS_CLI" ]
then
	echo "Using $JENKINS_CLI."
else
	wget -O "$JENKINS_CLI" $JENKINS_CJOC_URL/jnlpJars/jenkins-cli.jar
fi

java -jar $JENKINS_CLI -s $JENKINS_CJOC_URL -auth $JENKINS_AUTH list-masters | jq -r '.data.masters[] | select(.status == "ONLINE") | .url' | while read url; do
	java -jar $JENKINS_CLI -s $url -auth $JENKINS_AUTH groovy = < configuration-script.groovy
	java -jar $JENKINS_CLI -s $url -auth $JENKINS_AUTH install-plugin beer
done

Push a Plugin Catalog to all Client Masters

The following bash script will add a Plugin Catalog to Operations Center and push it to all the online Client Masters:

#!/usr/bin/env bash

JENKINS_CLI=jenkins-cli.jar
JENKINS_CJOC_URL=http://localhost:8080/
JENKINS_AUTH=admin:admin

if [ -z "$JENKINS_CJOC_URL" ]; then
    echo "Need to set environment variable JENKINS_CJOC_URL (Operations Center root URL)."
    exit 1
fi

if [ -z "$JENKINS_AUTH" ]; then
    echo "Need to set environment variable JENKINS_AUTH (format: 'userId:apiToken')."
    exit 1
fi


if [ -f "$JENKINS_CLI" ]
then
	echo "Using $JENKINS_CLI."
else
	wget -O "$JENKINS_CLI" $JENKINS_CJOC_URL/jnlpJars/jenkins-cli.jar
fi

java -jar $JENKINS_CLI -s $JENKINS_CJOC_URL -auth $JENKINS_AUTH  plugin-catalog --put < "java-web-catalog.json" | jq

java -jar $JENKINS_CLI -s $JENKINS_CJOC_URL -auth $JENKINS_AUTH list-masters | jq -r '.data.masters[] | select(.status == "ONLINE") | .fullName' | while read masterName; do
	java -jar $JENKINS_CLI -s $JENKINS_CJOC_URL -auth $JENKINS_AUTH plugin-catalog --push "java-web" --master "$masterName" | jq
done

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’re using Bash:

  1. Change 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:

    #!/bin/sh
    
    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 (such as jenkins-cli.sh).
    Note: This alias file assumes that jenkins-cli.jar is located in the same directory.

  5. Make the alias file executable.

     chmod a+x jenkins-cli.sh
  6. Configure the actual alias to your alias file in your appropriate Bash configuration file (.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/jenkins-cli.sh'
  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
      or

    • 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 previous section examples of usage 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

Configuring the Jenkins CLI tool to work with non-TrustStore SSL certificates

If your CloudBees Core or CloudBees Jenkins Distribution instance has been secured with a non-TrustStore SSL certificate, then you may need to configure your local machine running the Jenkins CLI tool, to allow it to successfully communicate with CloudBees Core or CloudBees Jenkins Distribution.

  1. Ensure that the keytool command is running on the machine running the Jenkins CLI tool.

  2. Obtain/download your CloudBees Core’s non-TrustStore SSL certificate directly from the web browser itself - naming it, for example, cloudbees-core.example.com.crt.

    In Firefox, this can be done by doing the following:

    1. Visit your CloudBees Core site.

    2. Click its padlock icon to the left of the URL field.

    3. Click the > to the right of Connection.

    4. Click More Information at the base of the resulting dialog box.

    5. In the resulting Page Info dialog box, ensure the Security tab is selected and click the View Certificate button.

    6. On the resulting Certificate Viewer dialog box, click the Details tab and click the Export button.

  3. Create a keystore and import this certificate by running the command (changing the values appropriately):

    keytool -import -noprompt -trustcacerts -alias cloudbees-core.example.com -file cloudbees-core.example.com.crt -keystore myKeystore -storepass changeme
  4. Test that the certificate configured in your keystore works and now provides your locally running Jenkins CLI tool access to your CloudBees Core instance by running this command:

    java -Djavax.net.ssl.trustStore=myKeystore -Djavax.net.ssl.trustStorePassword=changeme -jar jenkins-cli.jar -s https://cloudbees-core.example.com/cjoc/ help

    If you receive a list of available Jenkins CLI commands in both cases, then your Jenkins CLI is now working.

  5. Update the alias file/s configured for your Jenkins CLI tool to insert these additional components between java and -jar:

    -Djavax.net.ssl.trustStore=myKeystore -Djavax.net.ssl.trustStorePassword=changeme
Copyright © 2010-2020 CloudBees, Inc.Online version published by CloudBees, Inc. under the Creative Commons Attribution-ShareAlike 4.0 license.CloudBees and CloudBees DevOptics are registered trademarks and CloudBees Core, CloudBees Flow, CloudBees Flow Deploy, CloudBees Flow DevOps Insight, CloudBees Flow DevOps Foresight, CloudBees Flow Release, CloudBees Accelerator, CloudBees Accelerator ElectricInsight, CloudBees Accelerator Electric Make, CloudBees CodeShip, CloudBees Jenkins Enterprise, CloudBees Jenkins Platform, CloudBees Jenkins Operations Center, and DEV@cloud are trademarks of CloudBees, Inc. Most CloudBees products are commonly referred to by their short names — Accelerator, Automation Platform, Flow, Deploy, Foresight, Release, Insight, and eMake — throughout various types of CloudBees product-specific documentation. Oracle and Java are registered trademarks of Oracle and/or its affiliates. Jenkins is a registered trademark of the non-profit Software in the Public Interest organization. Used with permission. See here for more info about the Jenkins project. The registered trademark Jenkins® is used pursuant to a sublicense from the Jenkins project and Software in the Public Interest, Inc. Read more at www.cloudbees.com/jenkins/about. Apache, Apache Ant, Apache Maven, Ant and Maven are trademarks of The Apache Software Foundation. Used with permission. No endorsement by The Apache Software Foundation is implied by the use of these marks.Other names may be trademarks of their respective owners. Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this content, and CloudBees was aware of a trademark claim, the designations have been printed in caps or initial caps. While every precaution has been taken in the preparation of this content, the publisher and authors assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein.