Jenkins CLI

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.

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.

The 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.

This is the default mode, though you may pass the -http option explicitly for clarity.

Authentication is preferably with an -auth option, which takes a username:apitoken argument. Get your API token from /me/configure:

(Actual passwords are also accepted, but this is discouraged.)

You can also precede the argument with @ to load the same content from a file:

An alternative authentication method is to configure environment variables in a similar way as the $JENKINS_URL is used. The username can be specified via the environment variable $JENKINS_USER_ID while the apitoken can be specified via the variable $JENKINS_API_TOKEN. Both variables have to be set all at once.

In case these environment variables are configured you could still override the authentication method using different credentials with the -auth option, which takes preference over them.

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.

In Jenkins 2.217 and above, the -webSocket mode may be used as an alternative to -http. The advantage is that a more standard transport is used, avoiding problems with many reverse proxies or the need for special proxy configuration.

Authentication is via SSH keypair. You must select the Jenkins user ID as well:

In this mode, the client acts essentially like a native ssh command.

By default the client will try to connect to an SSH port on the same host as is used in the JENKINS_URL. If Jenkins is behind an HTTP reverse proxy, this will not generally work, so run Jenkins with the system property -Dorg.jenkinsci.main.modules.sshd.SSHD.hostName=ACTUALHOST to define a hostname or IP address for the SSH endpoint.

You may get the error below and find a log entry just below that concerning mismatched keys:

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. [localhost]:3485). 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:

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:

When you try to authenticate, you can then refresh the page and see what happen internally.