Jenkins CLI

Jenkins CLI cheatsheet — trigger builds, get job status, manage nodes. java -jar jenkins-cli.jar build job-name, list-jobs, console. Full Jenkins CLI reference.

13 min read

What it is

Jenkins CLI is a command-line interface for interacting with and managing a Jenkins instance, useful for scripting administrative tasks, triggering builds, and retrieving build information.

Installation

Linux / macOS

  1. Download the jenkins-cli.jar file from your Jenkins instance: Navigate to http://<your-jenkins-url>/jnlpJars/jenkins-cli.jar and save the file.
  2. Place the jenkins-cli.jar in a convenient location (e.g., ~/bin/).
  3. Make it executable:
    chmod +x ~/bin/jenkins-cli.jar
  4. You can then invoke it using java -jar ~/bin/jenkins-cli.jar. For convenience, create an alias or a shell script.

Windows

  1. Download the jenkins-cli.jar file from your Jenkins instance: Navigate to http://<your-jenkins-url>/jnlpJars/jenkins-cli.jar and save the file.
  2. Place the jenkins-cli.jar in a convenient location (e.g., C:\JenkinsCLI\).
  3. You can then invoke it using java -jar C:\JenkinsCLI\jenkins-cli.jar.

Authentication

The CLI uses either API tokens or SSH keys for authentication.

API Token:

  1. In Jenkins, go to Your username > Configure > API Token.
  2. Click Add new Token, give it a name (e.g., cli_token), and copy the generated token.
  3. When using the CLI, you’ll typically provide credentials like:
    java -jar jenkins-cli.jar -auth <your-username>:<your-api-token> ...
    Or set them via environment variables:
    export JENKINS_USER=<your-username>
export JENKINS_API_TOKEN=<your-api-token>
java -jar jenkins-cli.jar ...

SSH Key:

  1. Generate an SSH key pair if you don’t have one:
    ssh-keygen -t rsa -b 4096 -f ~/.ssh/jenkins_cli_id_rsa
  2. Add the public key (~/.ssh/jenkins_cli_id_rsa.pub) to your Jenkins user’s ~/.ssh/authorized_keys file.
  3. When using the CLI, specify the private key:
    java -jar jenkins-cli.jar -ssh -i ~/.ssh/jenkins_cli_id_rsa ...

Core Concepts

  • Jenkins URL: The base URL of your Jenkins instance (e.g., http://localhost:8080).
  • Credentials: How the CLI authenticates with Jenkins (username/API token or SSH key).
  • Command Namespace: Commands are often grouped under namespaces (e.g., build, node, plugin).
  • Item Name: Refers to Jenkins jobs, folders, or other configuration items.

Commands / Usage

All commands are invoked via java -jar jenkins-cli.jar [options] <command>.

Connection Options

These options are global and usually specified first.

  • Specify Jenkins URL:

    java -jar jenkins-cli.jar -s http://localhost:8080 ...

    Specifies the Jenkins server URL.

  • Basic Authentication (Username/API Token):

    java -jar jenkins-cli.jar -auth <username>:<api-token> -s http://localhost:8080 ...

    Authenticates using username and API token.

  • SSH Authentication (Private Key):

    java -jar jenkins-cli.jar -ssh -i ~/.ssh/jenkins_cli_id_rsa -s http://localhost:8080 ...

    Authenticates using an SSH private key.

  • Timeout:

    java -jar jenkins-cli.jar -timeout 60000 -s http://localhost:8080 ...

    Sets the connection timeout in milliseconds.

Building Jobs

Triggering builds and checking their status.

  • Build a job:

    java -jar jenkins-cli.jar -s http://localhost:8080 build my-job

    Triggers a build for the job named my-job.

  • Build a job with parameters:

    java -jar jenkins-cli.jar -s http://localhost:8080 build my-job -p PARAM1=value1 -p PARAM2=value2

    Triggers a build for my-job with specified build parameters.

  • Build a job and wait for completion:

    java -jar jenkins-cli.jar -s http://localhost:8080 build my-job -w

    Triggers a build for my-job and waits until it’s finished.

  • Build a job and wait, returning exit code based on build status:

    java -jar jenkins-cli.jar -s http://localhost:8080 build my-job -w -v

    Waits for the build to complete and returns a non-zero exit code if the build failed or was unstable.

  • Build a job in a folder:

    java -jar jenkins-cli.jar -s http://localhost:8080 build "My Folder/my-job"

    Triggers a build for a job located within a folder.

  • Get build status:

    java -jar jenkins-cli.jar -s http://localhost:8080 get-build my-job 5

    Retrieves the status of build number 5 for my-job.

  • Get the latest build status:

    java -jar jenkins-cli.jar -s http://localhost:8080 get-build my-job

    Retrieves the status of the last completed build for my-job.

  • Get build console output:

    java -jar jenkins-cli.jar -s http://localhost:8080 console my-job 10

    Retrieves the console output for build number 10 of my-job.

  • Get latest build console output:

    java -jar jenkins-cli.jar -s http://localhost:8080 console my-job

    Retrieves the console output for the last completed build of my-job.

Job Management

Creating, deleting, and configuring jobs.

  • List jobs in the root folder:

    java -jar jenkins-cli.jar -s http://localhost:8080 list-jobs

    Lists all top-level jobs.

  • List jobs in a folder:

    java -jar jenkins-cli.jar -s http://localhost:8080 list-jobs "My Folder"

    Lists jobs within the specified folder.

  • Create a job from an XML file:

    java -jar jenkins-cli.jar -s http://localhost:8080 create-job my-new-job < /path/to/config.xml

    Creates a new job named my-new-job using the configuration from config.xml.

  • Update a job from an XML file:

    java -jar jenkins-cli.jar -s http://localhost:8080 update-job my-job < /path/to/updated_config.xml

    Updates the configuration of my-job with the content from updated_config.xml.

  • Get job configuration:

    java -jar jenkins-cli.jar -s http://localhost:8080 get-job my-job > my-job-backup.xml

    Retrieves the XML configuration for my-job and saves it to a file.

  • Delete a job:

    java -jar jenkins-cli.jar -s http://localhost:8080 delete-job my-old-job

    Deletes the job named my-old-job.

  • Copy a job:

    java -jar jenkins-cli.jar -s http://localhost:8080 copy-job my-job my-job-copy

    Copies my-job to a new job named my-job-copy.

  • Enable a job:

    java -jar jenkins-cli.jar -s http://localhost:8080 enable-job my-job

    Enables the job my-job.

  • Disable a job:

    java -jar jenkins-cli.jar -s http://localhost:8080 disable-job my-job

    Disables the job my-job.

Node Management (Agents)

Managing Jenkins agents.

  • List all nodes (agents and master):

    java -jar jenkins-cli.jar -s http://localhost:8080 list-nodes

    Lists all connected nodes.

  • Get node information:

    java -jar jenkins-cli.jar -s http://localhost:8080 show-node myslave

    Displays detailed information about the node named myslave.

  • Delete a node:

    java -jar jenkins-cli.jar -s http://localhost:8080 delete-node myslave

    Deletes the node named myslave.

  • Disconnect a node:

    java -jar jenkins-cli.jar -s http://localhost:8080 disconnect-node myslave

    Disconnects the node myslave from Jenkins.

  • Connect a node:

    java -jar jenkins-cli.jar -s http://localhost:8080 connect-node myslave

    Connects the node myslave to Jenkins.

Plugin Management

Installing and managing plugins.

  • List installed plugins:

    java -jar jenkins-cli.jar -s http://localhost:8080 list-plugins

    Lists all installed plugins and their versions.

  • Install a plugin:

    java -jar jenkins-cli.jar -s http://localhost:8080 install-plugin git

    Installs the Git plugin.

  • Install a plugin with a specific version:

    java -jar jenkins-cli.jar -s http://localhost:8080 install-plugin workflow-aggregator:2.6

    Installs version 2.6 of the Workflow Aggregator plugin.

  • Install a plugin from a URL:

    java -jar jenkins-cli.jar -s http://localhost:8080 install-plugin http://updates.jenkins-ci.org/download/plugins/ssh-agent/1.13/ssh-agent.hpi

    Installs the SSH Agent plugin from a direct URL.

  • Uninstall a plugin:

    java -jar jenkins-cli.jar -s http://localhost:8080 uninstall-plugin mailer

    Uninstalls the Mailer plugin.

System Information and Management

Retrieving system status and performing administrative actions.

  • Get Jenkins version:

    java -jar jenkins-cli.jar -s http://localhost:8080 version

    Prints the Jenkins version.

  • Get system information:

    java -jar jenkins-cli.jar -s http://localhost:8080 system-info

    Prints detailed system information.

  • Get Jenkins configuration:

    java -jar jenkins-cli.jar -s http://localhost:8080 get-config

    Retrieves the global Jenkins configuration XML.

  • Update Jenkins configuration:

    java -jar jenkins-cli.jar -s http://localhost:8080 update-config < /path/to/jenkins.xml

    Updates the global Jenkins configuration from an XML file.

  • Restart Jenkins:

    java -jar jenkins-cli.jar -s http://localhost:8080 restart

    Restarts the Jenkins instance.

  • Safe Restart Jenkins:

    java -jar jenkins-cli.jar -s http://localhost:8080 safe-restart

    Initiates a safe restart, allowing current builds to complete.

  • Reload Jenkins configuration:

    java -jar jenkins-cli.jar -s http://localhost:8080 reload

    Reloads the Jenkins configuration from disk.

  • Shutdown Jenkins:

    java -jar jenkins-cli.jar -s http://localhost:8080 shutdown

    Shuts down the Jenkins instance.

Script Console

Executing Groovy scripts on the Jenkins master.

  • Execute a Groovy script:

    java -jar jenkins-cli.jar -s http://localhost:8080 groovy -f /path/to/script.groovy

    Executes a Groovy script file.

  • Execute a Groovy script with inline code:

    java -jar jenkins-cli.jar -s http://localhost:8080 groovy "println 'Hello from CLI'"

    Executes the given Groovy code directly.

User Management

Managing Jenkins users.

  • List users:

    java -jar jenkins-cli.jar -s http://localhost:8080 list-users

    Lists all Jenkins users.

  • Get user information:

    java -jar jenkins-cli.jar -s http://localhost:8080 get-user johndoe

    Retrieves details for the user johndoe.

  • Create a user:

    java -jar jenkins-cli.jar -s http://localhost:8080 create-user jane.doe --password secretpassword --full-name "Jane Doe" --email jane.doe@example.com

    Creates a new user with specified details.

  • Update a user:

    java -jar jenkins-cli.jar -s http://localhost:8080 update-user john.doe --email john.doe@example.com

    Updates the email for the user john.doe.

  • Delete a user:

    java -jar jenkins-cli.jar -s http://localhost:8080 delete-user olduser

    Deletes the user olduser.

Credentials Management

Managing Jenkins credentials.

  • List credentials in a domain:

    java -jar jenkins-cli.jar -s http://localhost:8080 list-credentials system::system::Jenkins

    Lists credentials in the global Jenkins domain.

  • List credentials in a folder:

    java -jar jenkins-cli.jar -s http://localhost:8080 list-credentials "My Folder"

    Lists credentials within a specific folder.

  • Create username/password credential:

    java -jar jenkins-cli.jar -s http://localhost:8080 create-credentials-binding username_password --id my-user-pass --username admin --password 'supersecret' --description "Admin credentials"

    Creates a new username/password credential.

  • Create secret text credential:

    java -jar jenkins-cli.jar -s http://localhost:8080 create-credentials-binding secret_text --id my-secret-token --secret "s3cr3tT0k3n" --description "API Token"

    Creates a new secret text credential.

  • Delete credential:

    java -jar jenkins-cli.jar -s http://localhost:8080 delete-credential system::system::Jenkins::my-user-pass

    Deletes the specified credential.

Other Useful Commands

  • Help:

    java -jar jenkins-cli.jar -s http://localhost:8080 help

    Displays help information for all commands.

  • Help for a specific command:

    java -jar jenkins-cli.jar -s http://localhost:8080 help build

    Displays help for the build command.

  • Get Jenkins status:

    java -jar jenkins-cli.jar -s http://localhost:8080 get-jenkins-status

    Retrieves the current status of the Jenkins instance.

  • Get Jenkins uptime:

    java -jar jenkins-cli.jar -s http://localhost:8080 get-jenkins-uptime

    Retrieves the uptime of the Jenkins instance.

Common Patterns

  • Triggering a build and tailing its output in real-time:

    java -jar jenkins-cli.jar -s http://localhost:8080 build my-job -w -v && echo "Build finished successfully" || echo "Build failed!"

    This command builds my-job, waits for completion (-w), and returns a non-zero exit code if the build fails (-v). The && and || operators provide immediate feedback on the build status.

  • Automating plugin installation and Jenkins restart:

    java -jar jenkins-cli.jar -s http://localhost:8080 install-plugin git
java -jar jenkins-cli.jar -s http://localhost:8080 install-plugin workflow-aggregator
java -jar jenkins-cli.jar -s http://localhost:8080 safe-restart

    Installs two plugins and then performs a safe restart to apply the changes.

  • Backing up job configurations:

    mkdir jenkins_job_backups
java -jar jenkins-cli.jar -s http://localhost:8080 list-jobs | while read job; do
  java -jar jenkins-cli.jar -s http://localhost:8080 get-job "$job" > "jenkins_job_backups/${job}.xml"
  echo "Backed up job: $job"
done

    This script iterates through all jobs, retrieves their XML configuration, and saves each to a separate file in a jenkins_job_backups directory.

  • Executing a script to update multiple jobs:

    # script.groovy
# import hudson.model.*
// Jenkins.instance.getAllItems(AbstractProject.class).each { project ->
//   if (project.name.startsWith("legacy-")) {
//     project.setQuietPeriod(5)
//     project.save()
//     println "Updated ${project.name}"
//   }
// }

java -jar jenkins-cli.jar -s http://localhost:8080 groovy -f update_jobs.groovy

    This executes a Groovy script that modifies properties of jobs matching a certain pattern.

  • Creating a folder and a job within it:

    # folder_config.xml
# <?xml version='1.1' encoding='UTF-8'?>
# <com.cloudbees.hudson.plugins.folder.Folder plugin="cloudbees-folder@6.16">
#   <properties/>
#   <icon class="com.cloudbees.hudson.plugins.folder.icons.StockFolderIcon"/>
# </com.cloudbees.hudson.plugins.folder.Folder>

# job_config.xml
# <?xml version='1.1' encoding='UTF-8'?>
# <org.jenkinsci.plugins.workflow.cps.CpsScmFlowDefinition plugin="workflow-cps@2698.v7952246085b_c">
#   <scm class="hudson.scm.NullSCM"/>
#   <definition class="org.jenkinsci.plugins.workflow.cps.CpsFlowDefinition">
#     <script>pipeline { agent any stages { stage('Hello') { steps { echo 'World' } } } }</script>
#     <sandbox>true</sandbox>
#   </definition>
#   <triggers/>
#   <quietPeriod>4</quietPeriod>
#   <properties/>
# </org.jenkinsci.plugins.workflow.cps.CpsScmFlowDefinition>

java -jar jenkins-cli.jar -s http://localhost:8080 create-job "My New Folder" < folder_config.xml
java -jar jenkins-cli.jar -s http://localhost:8080 create-job "My New Folder/my-pipeline-job" < job_config.xml

    This sequence creates a Jenkins folder and then creates a Pipeline job inside that folder.

Gotchas

  • JAR File Location: Always ensure jenkins-cli.jar is accessible and the path is correct. Using java -jar /path/to/jenkins-cli.jar is safer than assuming it’s in your PATH.
  • Authentication Methods: Mixing -auth and -ssh is not allowed. Choose one method and stick to it. Environment variables (JENKINS_USER, JENKINS_API_TOKEN) can simplify repeated commands.
  • Item Names with Spaces: Job names or folder names containing spaces must be quoted, e.g., "My Folder/My Job".
  • Script Console Security: Be extremely cautious when running arbitrary Groovy scripts via groovy. Malicious scripts can compromise your Jenkins instance. Always review scripts thoroughly.
  • Plugin Installation Dependencies: Installing plugins might require other plugins to be installed first. The CLI might not automatically resolve all dependencies, leading to errors. Check Jenkins logs for details.
  • Job XML Format: Ensure the XML configuration files used for create-job and update-job are valid and compatible with your Jenkins version and installed plugins.
  • Permissions: The user credentials used for authentication must have the necessary permissions in Jenkins to perform the requested actions (e.g., triggering builds, deleting jobs, managing nodes).
  • Long-Running Commands: Commands like build -w can hang if Jenkins becomes unresponsive. Use timeouts (-timeout) where appropriate.
  • CLI Version Compatibility: While generally backward compatible, it’s best practice to use a jenkins-cli.jar version that closely matches your Jenkins server version for optimal compatibility.