The Jenkins CLI is a small program that lets you send commands to a Jenkins server from a terminal.

Let us take the name apart. Jenkins is a free automation server that builds, tests and delivers software. CLI stands for command-line interface. A command-line interface is a way of controlling a program by typing text commands rather than clicking with a mouse. A terminal is the text window where you type such commands. On many computers it is called Command Prompt, PowerShell, Terminal or Shell.

The Jenkins CLI is delivered as a single file, a Java program packaged as a JAR file, which is simply a bundle of Java code that can be run. It is named jenkins-cli.jar. You download it from your own Jenkins server, run it with Java, tell it the address of your server, and then give it a command such as “list my jobs” or “build this job”. The CLI sends your command to Jenkins over the network, Jenkins carries it out, and the answer is printed in your terminal.

It is important to see what the CLI is not. It is not a separate copy of Jenkins, and it does not run builds by itself. It is only a remote control. All the real work still happens inside the Jenkins server, using the same permissions and rules as the web pages.

The web interface is great for looking and learning. The CLI is great for repeating, scripting and automating.

You may wonder why anyone would type commands when clicking works fine. The answer is that clicking does not scale. If you need to change fifty jobs, clicking fifty times is slow and easy to get wrong. If you need to run the same task every night, nobody wants to click at midnight. A command can be saved in a file, reviewed by a colleague, repeated without mistakes and run by a schedule.

A short look under the bonnet makes everything else easier to understand.

The CLI has two halves. On your computer runs the client, the jenkins-cli.jar program. On the Jenkins server runs the server side, a built-in service that listens for CLI connections. The client opens a connection, sends your command and your identity, and waits. The server checks who you are, checks whether you may do that, runs the command and sends the answer back.

sequenceDiagram
    participant U as You in a terminal
    participant C as jenkins-cli.jar client
    participant S as Jenkins server
    U->>C: Type a command such as list-jobs
    C->>S: Connect and send the command with your identity
    S->>S: Check who you are and what you may do
    alt Allowed
        S->>S: Run the command
        S-->>C: Send the result
        C-->>U: Print the result in the terminal
    else Not allowed
        S-->>C: Send an error, for example missing permission
        C-->>U: Print the error
    end
    

Notice the last step. Like most command-line programs, the CLI returns an exit code when it finishes: zero means success and any other number means something went wrong. Scripts use this number to decide what to do next, such as stopping when a command fails.

Setting up takes only a few small things. Check this list before you start.

Downloading the CLI

The CLI file comes from your own Jenkins server, not from a website. This matters: the client and the server should be the same version family, so downloading it from your server guarantees a match. In the web interface, look in the Manage Jenkins area for a page about the Jenkins CLI, which describes the connection options and provides the download link. The file is also available at a fixed address on your server, ending in the path /jnlpJars/jenkins-cli.jar. Save it in a folder you can find easily.

Jenkins never carries out commands for strangers. You must show identity every time, and the safest way is an API token.

Authentication means proving who you are. With the web pages, you sign in with a username and password. The CLI needs to do the same job without a browser, and there are a few ways to do it.

What is an API token?

An API token is a long random text that acts like a password but is made only for programs. You create it in your own Jenkins user settings, in the Security section, by pressing a button to add a new token and giving it a name. Jenkins shows the token once. Copy it and store it safely, because it cannot be shown again. If a token is ever lost or leaked, you simply delete it and create another, and your real password remains untouched.

flowchart TD
    A["You sign in to the Jenkins web page"] --> B["Open your user settings and go to Security"]
    B --> C["Add a new API token and name it"]
    C --> D["Copy the token shown once"]
    D --> E["Store it in a safe place, such as a secrets manager"]
    E --> F["Give it to the CLI by option or environment variable"]
    F --> G{"Token leaked or lost?"}
    G -->|Yes| H["Delete it and create a new one"]
    G -->|No| I["Keep using it, and rotate it on a schedule"]
    

Giving credentials to the CLI

The CLI accepts the user and token in a single option, joined by a colon. It can also read them from a file, and it can read the server address and user details from environment variables named JENKINS_URL, JENKINS_USER_ID and JENKINS_API_TOKEN. An environment variable is a named value stored in your terminal session, like a sticky note that programs can read. Using them keeps secrets out of the command text, so they do not appear in your typing history.

The CLI can talk to Jenkins in more than one way. Choosing the right one depends on your network.

flowchart LR
    CL["CLI client"] -->|HTTP or HTTPS| J["Jenkins server"]
    CL -->|WebSocket| J
    CL -->|SSH| SS["Jenkins SSH service on its own port"]
    SS --> J
    

For a beginner, the easiest path is the default web-based method with an API token. Use the secure HTTPS address of your server whenever your organisation provides one. Plain HTTP sends everything, including your token, in readable form across the network.

Start with commands that only look, never change anything. They build confidence and prove the connection works.

A complete first command has three parts: the way to run the program, the connection details, and the command name. In words: run Java with the JAR file, tell it the server address and your credentials, and then name the command, for example java -jar jenkins-cli.jar -s YOUR_JENKINS_ADDRESS -auth USER:TOKEN who-am-i. If the reply shows your username, everything is set up correctly.

Once the connection works, these are the commands that most people use daily.

Starting builds

The build command starts a job. By default it simply asks Jenkins to add a build to the queue and returns immediately, leaving the build to run on its own. That is perfect for “fire and forget” tasks. When you want the CLI to wait until the build finishes and then return a result you can act on, add the option that waits for completion. When you also want to watch the output while it runs, add the option that shows the log as it happens. If the job takes parameters, you can supply their values in the same command, one pair of name and value at a time.

flowchart TD
    S["Script starts"] --> B["CLI: build the job with a parameter"]
    B --> Q{"Wait for completion?"}
    Q -->|No| R["Command returns at once, build runs in the background"]
    Q -->|Yes| W["CLI waits and follows the log"]
    W --> X{"Build result"}
    X -->|Success| OK["Script continues to the next task"]
    X -->|Failure| ER["Script stops and reports the problem"]
    

Job configuration as XML

Jenkins stores each job’s settings as an XML document, a structured text format made of nested tags, like a form written out as text. The get-job command prints that document. The create-job and update-job commands accept one. This opens up powerful habits: you can back up every job’s configuration to files, compare two jobs, or create a hundred similar jobs from one template by changing only the names and addresses.

Administrators use the CLI to keep the server healthy. These commands need higher permissions, so ordinary users usually cannot run them.

A typical maintenance routine, written in plain words, might be: tell Jenkins to stop starting new builds, wait for running builds to finish, install or update plugins, perform a safe restart, and then lift the restriction. Every one of these steps can be a single CLI command, which makes the routine easy to save in a script and repeat safely.

sequenceDiagram
    participant A as Admin script
    participant J as Jenkins
    A->>J: quiet-down, stop starting new builds
    J-->>A: Accepted
    A->>J: Wait until running builds end
    A->>J: Install or update plugins
    A->>J: safe-restart
    J-->>A: Restarts when idle
    A->>J: cancel-quiet-down after the restart
    J-->>A: Normal work resumes
    

The real power of the CLI appears when commands are combined. A script is just a saved list of commands.

A script is a text file containing commands that run one after another. You can write one in the shell language of your computer, and run it by hand or on a schedule. Because the CLI returns an exit code, a script can check whether each command succeeded and decide what to do next.

Rules for good scripts

• Check every result. Look at the exit code of each CLI call and stop when something fails, rather than pressing on after an error.
• Keep secrets out of the file. Read the address, user and token from environment variables or a protected secret store.
• Print clear messages. Say what the script is about to do and what happened, so the log makes sense later.
• Test on a practice server first. Especially for commands that change or delete things.
• Start with read-only commands. Add changing commands only when the reading part works.
• Keep scripts in version control. Reviewed, tracked scripts are safer than files that live on one person’s laptop.

Jenkins offers several ways to control it. Knowing when to use each avoids frustration.

flowchart TD
    N["I want to control Jenkins"] --> Q1{"One-off or occasional task?"}
    Q1 -->|Yes| W["Use the web interface"]
    Q1 -->|No| Q2{"Simple admin or scripting from a terminal?"}
    Q2 -->|Yes| C["Use the CLI"]
    Q2 -->|No| Q3{"Integrating another program or dashboard?"}
    Q3 -->|Yes| R["Use the REST API"]
    Q3 -->|No| P["Consider Pipeline or Configuration as Code"]
    

Other tools also deserve a mention. Pipelines describe your build and delivery flow as code inside your repository. Configuration as Code describes the Jenkins server setup in files. The Script Console is a powerful administrator screen that runs code directly inside Jenkins. The CLI sits comfortably among them as the simple, scriptable remote control for everyday tasks.

The CLI is powerful, so it deserves the same care as the keys to the building.

The CLI does not bypass any rules. Every command runs as the user who signed in, and only if that user has the required permission. A permission is a right to do one kind of thing, such as read a job, start a build, or change global settings. This is why an ordinary developer can typically start builds of their own projects but cannot install plugins or restart the server.

flowchart LR
    T["CLI command with token"] --> AU["Jenkins authenticates the user"]
    AU --> PM{"Does the user have the permission?"}
    PM -->|Yes| RUN["Command runs and is logged"]
    PM -->|No| DEN["Command refused with an error"]
    

Most CLI problems fall into a few families. The message tells you where to look.

Every tool has a price. Here is an honest view of the CLI.

The main trade-off is convenience versus control. Clicking is forgiving: you can see what you are about to do. Commands are unforgiving: they do exactly what you type, immediately, at any scale. The remedy is not to avoid the CLI, but to build habits of previewing, testing on practice systems and keeping backups.

A pattern is a proven habit. An anti-pattern is a tempting shortcut that causes trouble later.

Patterns worth copying

Anti-patterns to avoid

A few steady habits keep the CLI helpful and safe.

Best practices

• Download the CLI from your own server. Refresh it after Jenkins upgrades.
• Use API tokens. Name them clearly, and delete the ones you no longer need.
• Use HTTPS. Keep certificate verification switched on.
• Test with who-am-i and version. Prove the connection before running anything important.
• Use help liberally. Your own server’s help output is the true list of available commands.
• Prefer safe restart and safe shutdown. Let running builds finish.
• Back up job configuration before changing it. Save the XML to a file first.
• Limit who can run powerful commands. Use roles and dedicated service users.
• Keep scripts small and readable. Print what they are doing and stop on the first error.

Common mistakes

Here is how teams use the CLI in everyday life. Details vary, but the shapes repeat.

The Jenkins CLI is a simple remote control for your Jenkins server. It is one small Java file that you download from your own server, run from a terminal, and point at the server with your username and an API token. Through it you can look at jobs and plugins, start builds and read their logs, create and copy jobs from XML, and perform careful administration such as safe restarts and plugin installation.

Its value comes from repetition. A command can be saved in a script, reviewed, scheduled and repeated without mistakes. Its risk comes from the same power: commands do exactly what you say, at any scale, immediately. Use tokens rather than passwords, give scripts narrow service accounts, keep secrets out of files, use HTTPS, check exit codes, and always test changing scripts on a practice server. With those habits, the CLI becomes one of the most reliable tools in your Jenkins toolbox.