More up-to-date information is available in the Jenkins documentation at https://jenkins.io/doc/book/managing/cli/
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.
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.
For details on authentication methods ("
-auth" parameter or
JENKINS_API_TOKEN environment variables), see Jenkins CLI > Client connection modes > HTTP connection mode.
The list of the available commands depends on the server you are talking to. Visit
https://jenkins.example.com/cli or use '
help' command to list them all:
More detailed help for individiual commands can be found by adding the command name after
The same information is available via the web UI, by clicking on a command name on the Jenkins CLI page.
Extending the CLI
Plugins installed on Jenkins server can add custom CLI commands. See Writing CLI commands for more details.
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
//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/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.
To use the
-i option the syntax is as follows:
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.
If your Jenkins requires authentication, use
--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.
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.
Operation timed out
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)
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 - X-SSH-Endpoint is not provided on top page when 401/403 are returned Closed but if you are using nginx as a proxy you could trick it to add this information instead of Jenkins.
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.
java.io.IOException / javax.net.ssl.SSLHandshakeException (SSL certificate issue)
You may face this issue if the certificate is not trusted, e.g. self-signed certificate.
see https://issues.jenkins-ci.org/browse/JENKINS-12629 for a way to trust a self-signed certificate (rather than using
java.io.IOException: No X-Jenkins-CLI2-Port
Solution: Go to Manage Jenkins -> Configure Global Security -> "TCP port for JNLP agents": choose fixed or random