Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 23 Next »

Jenkins has a built-in command line client 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.

Obtaining CLI

Jenkins CLI is distributed inside jenkins.war as a jar file. See for where to download the CLI jar file. 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.

Running CLI

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

java -jar jenkins-cli.jar [-s JENKINS_URL] command [options...] [arguments...]

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. The 'help' command will give you the list of the available commands, which depends on the server you are talking to.

Extending CLI

Plugins installed on Jenkins server can add custom CLI commands. See writing CLI commands for more details.

Working with Credentials

1.419 and later

If your Jenkins requires authentication, you should set up public key authentication. Login from the web UI and go to, 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.

To use the -i option the syntax is as follows:

java -jar jenkins-cli.jar [-s JENKINS_URL] [-i PRIVATE_KEY] command [options...] [arguments...]

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.

  1. Jenkins listens on a TCP/IP port configured under "TCP port for JNLP slave agents" in the system configuration page. This single port is used for both slaves and CLI.
  2. Jenkins advertises this port number as a special HTTP header (if disabled, this header will not be present.)
  3. CLI client will make an HTTP request to the top page of Jenkins, looking for this header.
  4. If the header is found and the TCP/IP port is identified, the client will attempt to connect to this URL.
  5. 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

Commons problems

Operation timed out

$ java -jar jenkins-cli.jar -s YOUR_SERVER_URL help
Exception in thread "main" Operation timed out
	at Method)
	at hudson.cli.CLI.<init>(
	at hudson.cli.CLI.<init>(
	at hudson.cli.CLI._main(
	at hudson.cli.CLI.main(

Check that the JNPL 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 YOUR_SERVER_URL login
Exception in thread "main"
	at hudson.cli.Connection.readBoolean(
	at hudson.cli.CLI.authenticate(
	at hudson.cli.CLI._main(
	at hudson.cli.CLI.main(

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

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

This issues was fixed in Jenkins 1.424

  • No labels