Jenkins has a built-in command line interface that allows you to access Jenkins from a script or from your shell. This is convenient for automation of routine tasks, bulk updates, trouble diagnosis, and so on.

This interface is accessed via the Jenkins CLI client, which is a Java JAR file distributed with Jenkins.

Obtaining the CLI client

You can download the JAR file for the client from the URL "/jnlpJars/jenkins-cli.jar" on your Jenkins server, e.g. https://jenkins.example.com/jnlpJars/jenkins-cli.jar In theory, the CLI JAR is dependent on the version of Jenkins, but in practice, we expect to be able to retain compatibility between different versions of Jenkins. In case of problems, just re-download the latest JAR from your Jenkins server.

Running a CLI command

The general syntax is as follows (the design is similar to tools like svn/git):

JENKINS_URL can be specified via the environment variable $JENKINS_URL. This environment variable is automatically set when Jenkins fork a process during builds, which allows you to use Jenkins CLI from inside the build without explicitly configuring the URL.

More detailed help for individiual commands can be found by adding the command name after help (e.g. help build). The same information is available via the web UI, by clicking on a command name on the Jenkins CLI page.

Extending the CLI

Working with Credentials

Jenkins accounts must have the Overall/Read account permission to access the CLI.

1.576 and later

Whenever the CLI tries to to connect to the Jenkins server, it offers the before mentioned SSH keys. When the user has those keys but doesn't want to use them to authenticate, it's possible to use the -noKeyAuth argument to skip being prompted for the key's password. This way the CLI will never try to use available SSH keys.

1.419 and later

If your Jenkins requires authentication, you should set up public key authentication. Login from the web UI and go to http://yourserver.com/me/configure, then set your public keys in the designated text area. When connecting to the server, the CLI will look for ~/.ssh/identity, ~/.ssh/id_dsa, ~/.ssh/id_rsa and use those to authenticate itself against the server. Alternatively, the -i option can be used to explicitly specify the location of the private key.

See the middle of this guide for how to generate SSH key pair, if you don't have one yet.

If you have used PuttyGen to generate your keys, you will have to convert them to openssh format. Otherwise Jenkins might silently ignore your keys and you will be Authenticated as: anonymous.

For compatibility reasons, unless you use the -i option, failure to authenticate by itself does not constitute a fatal error. It will instead try to execute the command anyway, as the anonymous user.

Before 1.419

If your Jenkins requires authentication, use --username and --password or --password-file options to specify the credentials. To avoid doing this for every command, you can also use the login CLI command once (with the same credentials parameters), and after that you may use other commands without specifying credentials. Note that not every authentication type supports these parameters for credentials. Prior to version 1.373, only authentication in Jenkins' own database was supported. As of 1.373, LDAP is also supported. If the CLI reports these are invalid parameters, file an issue for your authentication type and ask them to extend AbstractPasswordBasedSecurityRealm instead of directly from SecurityRealm to get support for these parameters.

Change History: Note that a security hole in CLI commands was fixed in version 1.371, and that CLI login did not work properly for many commands until 1.375.

Connection mechanism

Jenkins CLI clients and Jenkins server establishes the communication in the following fashion.

Jenkins listens on a TCP/IP port configured under "TCP port for JNLP agents" in the system configuration page. This single port is used for both agents and CLI.

Jenkins advertises this port number as a special HTTP header (if disabled, this header will not be present).

CLI client will make an HTTP request to the top page of Jenkins, looking for this header.

If the header is found and the TCP/IP port is identified, the client will attempt to connect to this URL.

If that fails (for example, if there's a reverse proxy and Jenkins runs on a different host, or if a firewall blocks access to this TCP/IP port), or if the header is not found, it will fall back to the communication mechanism that uses two simultaenous HTTP connections.

Use 1.427 for the fallback behavior

Up until 1.426, if the server advertises a separate TCP/IP port, then a client failure to connect to this port was fatal. Since 1.427, the client is improved to fall back to HTTP-based mechanism. See JENKINS-10611

Configuring TCP/IP port for CLI and agents.

You have to configure global security in order to select the port (rather than system configuration). Using a fixed port allows you to configure your firewall more easily.

Commons problems

Operation timed out

$ java -jar jenkins-cli.jar -s YOUR_SERVER_URL help
Exception in thread "main" java.net.ConnectException: Operation timed out
at java.net.PlainSocketImpl.socketConnect(Native Method)
at java.net.PlainSocketImpl.doConnect(PlainSocketImpl.java:351)
at java.net.PlainSocketImpl.connectToAddress(PlainSocketImpl.java:213)
at java.net.PlainSocketImpl.connect(PlainSocketImpl.java:200)
at java.net.SocksSocketImpl.connect(SocksSocketImpl.java:432)
at java.net.Socket.connect(Socket.java:529)
at java.net.Socket.connect(Socket.java:478)
at java.net.Socket.<init>(Socket.java:375)
at java.net.Socket.<init>(Socket.java:189)
at hudson.cli.CLI.<init>(CLI.java:97)
at hudson.cli.CLI.<init>(CLI.java:82)
at hudson.cli.CLI._main(CLI.java:250)
at hudson.cli.CLI.main(CLI.java:199)

Check that the JNLP port is opened if you are using a firewall on your server. You can configure its value in Jenkins configuration. By default it is set to use a random port.

If on the server side you have such logs (perhaps with another security manager)

INFO: Accepted connection #54 from /88.171.115.235:60876
Exception in thread "Thread-3518" java.lang.UnsupportedOperationException: Not giving you the password
at com.atlassian.crowd.integration.acegi.user.CrowdUserDetails.getPassword(CrowdUserDetails.java:52)
at hudson.model.User.impersonate(User.java:250)
at org.jenkinsci.main.modules.cli.auth.ssh.SshCliAuthenticator.authenticate(SshCliAuthenticator.java:44)
at hudson.cli.CliManagerImpl$1.run(CliManagerImpl.java:99)

This issues was fixed in Jenkins 1.424

WARNING: No header 'X-SSH-Endpoint' returned by Jenkins

You may get this error, which usually prevents you from using SSH CLI due to
JENKINS-45651
-
Getting issue details...STATUS
but if you are using nginx as a proxy you could trick it to add this information instead of Jenkins.

add_header 'X-SSH-Endpoint' 'jenkins.example.com:50022' always;

If you hit this, please be sure you add a comment on that bug in order to assure that it is reopened and fixed correctly.

You may face this issue if the certificate is not trusted, e.g. self-signed certificate.

bash-4.1$ java -jar jenkins-cli.jar -s https://jenkins.example.com/ help
Exception in thread "main" java.io.IOException: Failed to connect to https://jenkins.example.com/
at hudson.cli.CLI.getCliTcpPort(CLI.java:274)
at hudson.cli.CLI.<init>(CLI.java:134)
at hudson.cli.CLIConnectionFactory.connect(CLIConnectionFactory.java:72)
at hudson.cli.CLI._main(CLI.java:469)
at hudson.cli.CLI.main(CLI.java:384)
Caused by: javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: \
PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: \
unable to find valid certification path to requested target
at sun.security.ssl.Alerts.getSSLException(Alerts.java:192)
at sun.security.ssl.SSLSocketImpl.fatal(SSLSocketImpl.java:1682)
at sun.security.ssl.Handshaker.fatalSE(Handshaker.java:257)
at sun.security.ssl.Handshaker.fatalSE(Handshaker.java:251)
at sun.security.ssl.ClientHandshaker.serverCertificate(ClientHandshaker.java:1168)
at sun.security.ssl.ClientHandshaker.processMessage(ClientHandshaker.java:153)
at sun.security.ssl.Handshaker.processLoop(Handshaker.java:609)
at sun.security.ssl.Handshaker.process_record(Handshaker.java:545)
at sun.security.ssl.SSLSocketImpl.readRecord(SSLSocketImpl.java:930)
at sun.security.ssl.SSLSocketImpl.performInitialHandshake(SSLSocketImpl.java:1175)
at sun.security.ssl.SSLSocketImpl.startHandshake(SSLSocketImpl.java:1202)
at sun.security.ssl.SSLSocketImpl.startHandshake(SSLSocketImpl.java:1186)
at sun.net.www.protocol.https.HttpsClient.afterConnect(HttpsClient.java:440)
at sun.net.www.protocol.https.AbstractDelegateHttpsURLConnection.connect(AbstractDelegateHttpsURLConnection.java:185)
at sun.net.www.protocol.https.HttpsURLConnectionImpl.connect(HttpsURLConnectionImpl.java:153)
at hudson.cli.CLI.getCliTcpPort(CLI.java:272)
... 4 more
Caused by: sun.security.validator.ValidatorException: \
PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: \
unable to find valid certification path to requested target
at sun.security.validator.PKIXValidator.doBuild(PKIXValidator.java:324)
at sun.security.validator.PKIXValidator.engineValidate(PKIXValidator.java:224)
at sun.security.validator.Validator.validate(Validator.java:235)
at sun.security.ssl.X509TrustManagerImpl.validate(X509TrustManagerImpl.java:147)
at sun.security.ssl.X509TrustManagerImpl.checkServerTrusted(X509TrustManagerImpl.java:230)
at sun.security.ssl.X509TrustManagerImpl.checkServerTrusted(X509TrustManagerImpl.java:270)
at sun.security.ssl.ClientHandshaker.serverCertificate(ClientHandshaker.java:1147)
... 15 more
Caused by: sun.security.provider.certpath.SunCertPathBuilderException: \
unable to find valid certification path to requested target
at sun.security.provider.certpath.SunCertPathBuilder.engineBuild(SunCertPathBuilder.java:197)
at java.security.cert.CertPathBuilder.build(CertPathBuilder.java:255)
at sun.security.validator.PKIXValidator.doBuild(PKIXValidator.java:319)
... 21 more

Unknown User (bimargulies@gmail.com)

$ ssh -p 38844 -i ~/.ssh/jenkins jenkins@localhost build
Argument "JOB" is required
java -jar jenkins-cli.jar build args...
Starts a build, and optionally waits for a completion.
Aside from general scripting use, this command can be
used to invoke another job from within a build of one job.
With the -s option, this command changes the exit code based on
the outcome of the build (exit code 0 indicates a success.)
With the -c option, a build will only run if there has been
an SCM change
JOB : Name of the job to build
-c : Check for SCM changes before starting the build, and if
there's no change, exit without doing a build
-p : Specify the build parameters in the key=value format.
-s : Wait until the completion/abortion of the command
-v : Prints out the console output of the build. Use with -s
-w : Wait until the start of the command
--username VAL : User name to authenticate yourself to Jenkins
--password VAL : Password for authentication. Note that passing a
password in arguments is insecure.
--password-file VAL : File that contains the password

and then I got that the buildparam1 and buildparam2 are the ones defined within the job, yet I need to set their value?!
I've been told by the guys I'm working with/for that the number of parameters supplied in the cli must match exactly to the parameters defined in the web UI job editing page. Which brings me to these questions:

Does the number of parameters matters? what if I supply an extra unused parameter? what if supply less? would it get the default value as I defined in the editor?

Is it possible ootb to re-use the credentials with which a job was invoked ?

For example, let's say I have 2 jobs:

1) RunMe

2) Target

Within job RunMe, if I invoke ant and make a call to jenkins-cli.jar with "enable-job" and "Target" as arguments, can it re-use the credentials with which RunMe was invoked ? I ask this in context of LDAP authentication. I tried and ran into "hudson.security.AccessDeniedException2: anonymous is missing the Configure permission".

many thanks that the CLI is very useful in my project, it will be perfect if a more detail guide or sample provided, such as when creates a new job it will read stdin as a configuration XML file, the question is how to define the XML file, what infomation is mandatory and what format we have to follow.

When I trying to run build job from CLI with parameters to plugins I
get the following error:
c:\Jenkins>java -jar jenkins-cli.jar -s %JENKINS_URL% build
"CCBL_Test" -p "PROJECTS=Test1,Test2"
CLI parameter submission is not supported for the class
com.cwctravel.hudson.plugins.extended_choice_parameter.ExtendedChoiceParame terDefinition
type. Please file a bug report for this.

In case I use other parameter for ClearCase UCM baseline plugin, I get
similar error:
c:\Jenkins>java -jar jenkins-cli.jar -s %JENKINS_URL% build
"CCBL_Test" -p "ClearCase UCM baseline=TestBL_21052012"
CLI parameter submission is not supported for the class
com.michelin.cio.hudson.plugins.clearcaseucmbaseline.ClearCaseUcmBaselinePa rameterDefinition
type. Please file a bug report for this

Is it possible plugins don't support CLI parameters??
What I'm doing wrong?

For some reason my main Jenkins instance is refusing the -v option when triggering a build.

Here is the output from our main server:

$ java -jar /tmp/jenkins-cli.jar -s http://jenkins-dev/ build
Argument "JOB" is required
java -jar jenkins-cli.jar build args...
Starts a build, and optionally waits for a completion.
Aside from general scripting use, this command can be
used to invoke another job from within a build of one job.
With the -s option, this command changes the exit code based on
the outcome of the build (exit code 0 indicates a success.)
With the -c option, a build will only run if there has been
an SCM change
JOB : Name of the job to build
-c : Check for SCM changes before starting the build, and if
there's no change, exit without doing a build
-p : Specify the build parameters in the key=value format.
-s : Wait until the completion/abortion of the command
--username VAL : User name to authenticate yourself to Jenkins
--password VAL : Password for authentication. Note that passing a
password in arguments is insecure.
--password-file VAL : File that contains the password

From my local test instance, running the same build of Jenkins but a lot less plugging:

$ java -jar /tmp/jenkins-cli.jar -s http://localhost:8080/ build
Argument "JOB" is required
java -jar jenkins-cli.jar build args...
Starts a build, and optionally waits for a completion.
Aside from general scripting use, this command can be
used to invoke another job from within a build of one job.
With the -s option, this command changes the exit code based on
the outcome of the build (exit code 0 indicates a success.)
With the -c option, a build will only run if there has been
an SCM change
JOB : Name of the job to build
-c : Check for SCM changes before starting the build, and if
there's no change, exit without doing a build
-p : Specify the build parameters in the key=value format.
-s : Wait until the completion/abortion of the command
-v : Prints out the console output of the build. Use with -s
-w : Wait until the start of the command
--username VAL : User name to authenticate yourself to Jenkins
--password VAL : Password for authentication. Note that passing a
password in arguments is insecure.
--password-file VAL : File that contains the password

Note how -v is missing on our main server, and I cannot figure out why this is happening. Is there a known plugin that would disable the use of -v?

Our settings on our jenkins are very strict. Our "Configure Global Security" page set the Anonymous login with only the "Discover Job" right. This prevent us from using the normal command line everyone use:

Isn't that weird that you told to set at least the Anonymous right to "Discover Job" for the people to be redirect automatically to the login page and that single right prevent jenkins-cli to use the base URL "http://our-jenkins/" ? Just asking.

From the tooltip of "Discover Job":

This permission grants discover access to jobs. Lower than read permissions, it allows you to redirect anonymous users to the login page when they try to access a job url. Without it they would get a 404 error and wouldnt be able to discover project names.

Exception in thread "main" java.io.IOException: PEM is encrypted, but no password was specified
at com.trilead.ssh2.crypto.PEMDecoder.decode(PEMDecoder.java:318)
at hudson.cli.CLI.loadKey(CLI.java:550)
at hudson.cli.CLI.loadKey(CLI.java:526)
at hudson.cli.CLI.tryEncryptedFile(CLI.java:578)
at hudson.cli.CLI._main(CLI.java:434)
at hudson.cli.CLI.main(CLI.java:384)

But begs the question: How do you specify the password then? — On Windows that is – judging from the source the system tries to read the console which does not work in Window.

Martin

PS: I really start to hate all ssh key security. It is always so hard to set up and to create scripts for.Give me the --username --password command line options back

I would like to add environment variables to “$JENKINS_URL/job/$JOB_NAME/$BUILD_ID/injectedEnvVars/",Is there any way？

（$JENKINS_URL/job/$JOB_NAME/$BUILD_ID/injectedEnvVars/api/json）

1. Plug-ins can not be used！Because I want to read real-time this environment variables.

2. jenkins-cli.jar set-env-variables [-s JENKINS_URL] can not be used ﻿﻿﻿﻿！Because only in the next "Execute shell" to read, and can not be added to “$JENKINS_URL/job/$JOB_NAME/$BUILD_ID/injectedEnvVars/".

I am still getting HTTP 403 error:
java.io.EOFException
at java.io.DataInputStream.readFully(DataInputStream.java:197)
at java.io.DataInputStream.readUTF(DataInputStream.java:609)
at java.io.DataInputStream.readUTF(DataInputStream.java:564)
at hudson.cli.CLI.connectViaCliPort(CLI.java:226)
at hudson.cli.CLI.<init>(CLI.java:128)
at hudson.cli.CLIConnectionFactory.connect(CLIConnectionFactory.java:72)
at hudson.cli.CLI._main(CLI.java:473)
at hudson.cli.CLI.main(CLI.java:384)
Suppressed: java.io.IOException: Server returned HTTP response code: 403 for URL: https://xd-build.ci.corp.adobe.com:12001/cli
at sun.net.www.protocol.http.HttpURLConnection.getInputStream0(HttpURLConnection.java:1840)
at sun.net.www.protocol.http.HttpURLConnection.getInputStream(HttpURLConnection.java:1441)
at sun.net.www.protocol.https.HttpsURLConnectionImpl.getInputStream(HttpsURLConnectionImpl.java:254)
at hudson.cli.FullDuplexHttpStream.<init>(FullDuplexHttpStream.java:78)
at hudson.cli.CLI.connectViaHttp(CLI.java:152)
at hudson.cli.CLI.<init>(CLI.java:132)
... 3 more

I would like to have a groovy script that executes a jenkins cli command. All I seem to find is the other way around. Does anyone have an example of a groovy script that would execute the jenkins cli? the groovy script would be executed inside a post function in jira. thank you.