jenkins-cli

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

jenkins-cli is the client half of the Jenkins command-line interface. It is not a native binary. You download `jenkins-cli.jar` from a running controller at `/jnlpJars/jenkins-cli.jar` and run it with java -jar. The same commands are available over SSH when the controller's built-in SSH server is enabled.The client sends the command name and arguments to the controller, which runs them. Plugins can add commands, so two controllers rarely have the same help output. A user needs the Overall/Read permission to use the CLI, plus whatever permission the specific command checks (Job/Build for build, Overall/Administer for groovy, install-plugin, and safe-restart).WebSocket is the default transport. -http is the older full-duplex HTTP mode. -ssh makes the jar behave like an SSH client against the controller's own SSH port. You can skip the jar entirely and use OpenSSH: read the `X-SSH-Endpoint` response header (for example with curl -sI against `/login`) to learn the port, which is closed until an administrator turns the SSH server on.

-s URL

Jenkins controller URL. Falls back to JENKINS_URL, then the legacy HUDSON_URL. A missing trailing slash is added.

Use the WebSocket transport. This is the default since Jenkins 2.391. Both client and controller need 2.217 or newer.

Use a pair of plain HTTP(S) connections instead of WebSocket. Some reverse proxies break this mode by buffering the body.

Use the controller SSH service instead of WebSocket. Requires -user. The SSH port must be open.

Jenkins user id for -ssh. That user must have a matching SSH public key registered. Ignored unless -ssh is set. Mutually exclusive with -auth.

SSH private key file for -ssh. If omitted, the client tries the usual default key locations.

Do not load an SSH private key. Conflicts with -i. Meaningful only with -ssh.

Require strict SSH host-key checking. Meaningful only with -ssh.

Username and password or API token for the HTTP and WebSocket transports. @FILE reads `username:secret` from a file, which is the recommended form. Mutually exclusive with -bearer.

Bearer token for the HTTP and WebSocket transports. @FILE reads the token from a file. Mutually exclusive with -auth.

Skip HTTPS certificate verification. Insecure.

Java log level for the client, for example FINE.

Print the client jar version and exit. Does not contact the controller.

JENKINS_URL

Controller URL used when -s is omitted.

Legacy fallback used only when JENKINS_URL is unset.

Used together when -auth and -bearer are omitted. Set both or neither. -auth overrides them. Generate the token under the user security page (`/me/security` or `/user/<id>/security`).

The command set depends on the controller and its plugins. help prints the live list. help command prints one command. These ship with current Jenkins core:help [command]

List commands, or show one command's usage.

Print the authenticated user and granted authorities.

Print the controller's Jenkins version.

Print job names. An optional view or item-group name limits the list.

Schedule a build. -c skips the build when SCM has no change. -w waits until it starts. -s waits until it finishes and passes interrupts through to the build (exit status follows the build). -f follows progress but does not pass interrupts through (interrupt exits 125). -v prints the console and is used with -s. -p may be repeated.

Print a build log. BUILD is a number or permalink. The default is the last build. -f follows a build still in progress. -n prints the last N lines.

Stop taking new builds. -block waits until running builds finish. -timeout caps that wait, in milliseconds.

Leave quiet-down mode.

Quiet down, then restart. Present since Jenkins 2.414. The message is shown to users.

Reload configuration from disk. Discards changes that were not saved.

Install a plugin. SOURCE is an update-center short name (`git`, or `git:5.0` for a minimum version), a URL, or = to read a plugin file from standard input. -deploy loads it without waiting for a reboot. -restart restarts Jenkins after a successful install.

List installed plugins, or one plugin.

Create a job from config XML on standard input. NAME may be a folder path such as `folder/job`.

Delete one or more jobs.

Run a Groovy script read from standard input on the controller. Requires Overall/Administer. Only = is accepted as the script argument.

Requires Java. Prefer a jar downloaded from the controller you are calling. A jar from another Jenkins line can fail in confusing ways.Clients older than Jenkins 2.54 are treated as insecure. -remoting is rejected. Do not keep using a remoting-era jar.-noCertificateCheck disables TLS verification. -auth user:token puts a secret in the process list. Prefer -auth @file or the environment variables.-http fails behind reverse proxies that buffer request or response bodies. Stay on the WebSocket default unless you have a reason to switch.-ssh connects to the host in the controller URL, which is wrong when Jenkins sits behind an HTTP reverse proxy. The controller then needs `-Dorg.jenkinsci.main.modules.sshd.SSHD.hostName` set to the real SSH host. A host-key change shows up as "Server key did not validate". Remove the stale line from `~/.ssh/known_hosts` only when you know the key change is legitimate.groovy runs inside the controller JVM. install-plugin -restart and safe-restart take the controller down. Current core does not ship the old immediate restart or shutdown commands.

The client dates from Hudson, written by Kohsuke Kawaguchi, and stayed with Jenkins after the 2011 fork. The Remoting transport was later removed as unsafe. WebSocket support arrived in Jenkins 2.217 and became the default in 2.391. safe-restart has been a core command since 2.414.

jenkins(1), java(1), ssh(1), curl(1)

Source code · Homepage · Documentation