% curl -Lv https://JENKINS_URL/login 2>&1 | grep 'X-SSH-Endpoint' < X-SSH-Endpoint: localhost:53801 %
Jenkins has a built-in command line interface that allows users and administrators to access Jenkins from a script or shell environment. This can be convenient for scripting of routine tasks, bulk updates, troubleshooting, and more.
The command line interface can be accessed over SSH or with the Jenkins CLI
.jar file distributed with Jenkins.
Use of the CLI client distributed with Jenkins 2.53 and older and Jenkins LTS 2.46.1 and older is not recommended for security reasons: while there are no currently known vulnerabilities, several have been reported and patched in the past, and the Jenkins Remoting protocol it uses is inherently vulnerable to remote code execution bugs, even “preauthentication” exploits (by anonymous users able to physically access the Jenkins network).
The client distributed with Jenkins 2.54 and newer and Jenkins LTS 2.46.2 and newer
is considered secure in its default (
In a new Jenkins installation, the SSH service is disabled by default. Administrators may choose to set a specific port or ask Jenkins to pick a random port in the Configure Global Security page. In order to determine the randomly assigned SSH port, inspect the headers returned on a Jenkins URL, for example:
% curl -Lv https://JENKINS_URL/login 2>&1 | grep 'X-SSH-Endpoint' < X-SSH-Endpoint: localhost:53801 %
With the random SSH port (
53801 in this example), and Authentication
configured, any modern SSH client may securely execute CLI commands.
Whichever user used for authentication with the Jenkins master must have the
Overall/Read permission in order to access the CLI. The user may require
additional permissions depending on the commands executed.
Authentication relies on
SSH-based public/private key authentication. In order to add an SSH public key
for the appropriate user, navigate to
https://JENKINS_URL/user/USERNAME/configure and paste an SSH public key
into the appropriate text area.
Jenkins has a number of built-in CLI commands which can be found in every
Jenkins environment, such as
list-jobs. Plugins may also provide
CLI commands; in order to determine the full list of commands available
in a given Jenkins environment, execute the CLI
% ssh -l kohsuke -p 53801 localhost help
The following list of commands is not comprehensive, but it is a useful starting point for Jenkins CLI usage.
One of the most common and useful CLI commands is
build, which allows the
user to trigger any job or Pipeline for which they have permission.
The most basic invocation will simply trigger the job or Pipeline and exit, but with the additional options a user may also pass parameters, poll SCM, or even follow the console output of the triggered build or Pipeline run.
% ssh -l kohsuke -p 53801 localhost help build java -jar jenkins-cli.jar build JOB [-c] [-f] [-p] [-r N] [-s] [-v] [-w] 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) and interrupting the command will interrupt the job. With the -f option, this command changes the exit code based on the outcome of the build (exit code 0 indicates a success) however, unlike -s, interrupting the command will not interrupt the job (exit code 125 indicates the command was interrupted). 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 -f : Follow the build progress. Like -s only interrupts are not passed through to the build. -p : Specify the build parameters in the key=value format. -s : Wait until the completion/abortion of the command. Interrupts are passed through to the build. -v : Prints out the console output of the build. Use with -s -w : Wait until the start of the command % ssh -l kohsuke -p 53801 localhost build build-all-software -f -v Started build-all-software #1 Started from command line by admin Building in workspace /tmp/jenkins/workspace/build-all-software [build-all-software] $ /bin/sh -xe /tmp/hudson1100603797526301795.sh + echo hello world hello world Finished: SUCCESS Completed build-all-software #1 : SUCCESS %
Similarly useful is the
console command, which retrieves the console output
for the specified build or Pipeline run. When no build number is provided, the
console command will output the last completed build’s console output.
% ssh -l kohsuke -p 53801 localhost help console java -jar jenkins-cli.jar console JOB [BUILD] [-f] [-n N] Produces the console output of a specific build to stdout, as if you are doing 'cat build.log' JOB : Name of the job BUILD : Build number or permalink to point to the build. Defaults to the last build -f : If the build is in progress, stay around and append console output as it comes, like 'tail -f' -n N : Display the last N lines % ssh -l kohsuke -p 53801 localhost console build-all-software Started from command line by kohsuke Building in workspace /tmp/jenkins/workspace/build-all-software [build-all-software] $ /bin/sh -xe /tmp/hudson1100603797526301795.sh + echo hello world yes Finished: SUCCESS %
who-am-i command is helpful for listing the current user’s credentials
and permissions available to the user. This can be useful when debugging the
absence of CLI commands due to the lack of certain permissions.
% ssh -l kohsuke -p 53801 localhost help who-am-i java -jar jenkins-cli.jar who-am-i Reports your credential and permissions. % ssh -l kohsuke -p 53801 localhost who-am-i Authenticated as: kohsuke Authorities: authenticated %
While the SSH-based CLI is fast and covers most needs, there may be situations where the CLI client distributed with Jenkins is a better fit. For example, the default transport for the CLI client is HTTP which means no additional ports need to be opened in a firewall for its use.
The CLI client can be downloaded directly from a Jenkins master at the URL
/jnlpJars/jenkins-cli.jar, in effect
While a CLI
.jar can be used against different versions of Jenkins, should
any compatibility issues arise during use, please re-download the latest
file from the Jenkins master.
The general syntax for invoking the client is as follows:
java -jar jenkins-cli.jar [-s JENKINS_URL] [global options...] command [command options...] [arguments...]
JENKINS_URL can be specified via the environment variable
Summaries of other general options can be displayed by running the client with no arguments at all.
There are three basic modes in which the 2.54+ / 2.46.2+ client may be used, selectable by global option:
This is the default mode as of 2.54 and 2.46.2, though you may pass the
-http option explicitly for clarity.
Authentication is preferably with an
-auth option, which takes a
Get your API token from
java -jar jenkins-cli.jar [-s JENKINS_URL] -auth kohsuke:abc1234ffe4a command ...
(Actual passwords are also accepted, but this is discouraged.)
You can also precede the argument with
@ to load the same content from a file:
java -jar jenkins-cli.jar [-s JENKINS_URL] -auth @/home/kohsuke/.jenkins-cli command ...
Generally no special system configuration need be done to enable HTTP-based CLI connections. If you are running Jenkins behind an HTTP(S) reverse proxy, ensure it does not buffer request or response bodies.
The HTTP(S) connection mode of the CLI in Jenkins 2.54 and newer does not work correctly behind an Apache HTTP reverse proxy server using mod_proxy. Workarounds include using a different reverse proxy such as Nginx or HAProxy, or using the SSH connection mode where possible. See JENKINS-47279.
Authentication is via SSH keypair. You must select the Jenkins user ID as well:
java -jar jenkins-cli.jar [-s JENKINS_URL] -ssh -user kohsuke command ...
In this mode, the client acts essentially like a native
By default the client will try to connect to an SSH port on the same host as is used in the
If Jenkins is behind an HTTP reverse proxy, this will not generally work,
so run Jenkins with the system property
to define a hostname or IP address for the SSH endpoint.
This was the only mode supported by clients downloaded from a pre-2.54 / pre-2.46.2 Jenkins server
(prior to the introduction of the
Its use is deprecated for security and performance reasons.
That said, certain commands or command modes can only run in Remoting mode,
typically because the command functionality involves running server-supplied code on the client machine.
This mode is disabled on the server side for new installations of 2.54+ and 2.46.2. If you must use it, and accept the risks, it may be enabled in Configure Global Security.
Authentication is preferably via SSH keypair.
login command and
--password command (note: not global) options are also available;
these are discouraged since they cannot work with a non-password-based security realm,
certain command arguments will not be properly parsed if anonymous users lack overall or job read access,
and saving human-chosen passwords for use in scripts is considered insecure.
Note that there are two transports available for this mode: over HTTP, or over a dedicated TCP socket. If the TCP port is enabled and seems to work, the client will use this transport. If the TCP port is disabled, or such a port is advertised but does not accept connections (for example because you are using an HTTP reverse proxy with a firewall), the client will automatically fall back to the less efficient HTTP transport.
There are a number of common problems that may be experienced when running the CLI client.
Check that the HTTP or TCP 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.
% java -jar jenkins-cli.jar -s JENKINS_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)
Go to Manage Jenkins > Configure Global Security and choose "Fixed" or "Random" under TCP port for JNLP agents.
java.io.IOException: No X-Jenkins-CLI2-Port among [X-Jenkins, null, Server, X-Content-Type-Options, Connection, X-You-Are-In-Group, X-Hudson, X-Permission-Implied-By, Date, X-Jenkins-Session, X-You-Are-Authenticated-As, X-Required-Permission, Set-Cookie, Expires, Content-Length, Content-Type] at hudson.cli.CLI.getCliTcpPort(CLI.java:284) 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: http://citest.gce.px/cli at sun.net.www.protocol.http.HttpURLConnection.getInputStream0(HttpURLConnection.java:1840) at sun.net.www.protocol.http.HttpURLConnection.getInputStream(HttpURLConnection.java:1441) 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
You may get the error below and find a log entry just below that concerning
org.apache.sshd.common.SshException: Server key did not validate at org.apache.sshd.client.session.AbstractClientSession.checkKeys(AbstractClientSession.java:523) at org.apache.sshd.common.session.helpers.AbstractSession.handleKexMessage(AbstractSession.java:616) ...
This means your SSH configuration does not recognize the public key presented by the server. It’s often the case when you run Jenkins in dev mode and multiple instances of the application are run under the same SSH port over time.
In a development context, access your
~/.ssh/known_hosts (or in
C:/Users/<your_name>/.ssh/known_hosts for Windows)
and remove the line corresponding to your current SSH port (e.g.
In a production context, check with the Jenkins administrator if the public key of the server changed recently.
If so, ask the administrator to do the the steps described above.
If your client displays a stacktrace that looks like:
org.acegisecurity.userdetails.UsernameNotFoundException: <name_you_used> ...
This means your SSH keys were recognized and validated against the stored users but the username is not valid for the security realm your application is using at the moment. This could occur when you were using the Jenkins database initially, configured your users, and then switched to another security realm (like LDAP, etc.) where the defined users do not exist yet.
To solve the problem, ensure your users exist in your configured security realm.
To get more information about the authentication process:
Go into Manage Jenkins > System Log > Add new log recorder.
Enter any name you want and click on Ok.
Click on Add
org.jenkinsci.main.modules.sshd.PublicKeyAuthenticatorImpl (or type
PublicKeyAuth and then select the full name)
Set the level to ALL.
Repeat the previous three steps for
Click on Save
When you try to authenticate, you can then refresh the page and see what happen internally.