Jenkins CLI and REST API

The Jenkins web page serves people. Scripts, chat bots, and other tools need a different door. Jenkins offers two: a command line client and a REST API. Both let programs start builds, read results, and manage jobs without a browser.

The Layman's View

A restaurant has a dining room for guests and a back door for suppliers. The dining room has menus and waiters. The back door has a simple form: drop the order, receive the goods. The web page is the dining room, and the CLI and API are the back door that machines use.

Choosing Between CLI and API

Point	CLI	REST API
Tool needed	Java and jenkins-cli.jar	Any HTTP tool such as curl
Best for	Admin chores and shell scripts	Integrations and dashboards
Output	Plain text	JSON, XML, or Python data

Creating an API Token

Both tools authenticate with your user name and an API token. Tokens work like app-specific passwords. You can revoke one without changing your login.

1. Click your user name at the top right of Jenkins.
2. Select Security, or Configure in older versions.
3. Under API Token, click Add new Token.
4. Name the token after its purpose and press Generate.
5. Copy the value immediately, since Jenkins shows it once.

Store the token in a password manager or a secrets vault. Never place it in a public repository.

Using the CLI

Download the client from your own server at /jnlpJars/jenkins-cli.jar. Run commands with the java command.

java -jar jenkins-cli.jar -s https://jenkins.example.com/ \
     -auth admin:YOUR_API_TOKEN help

Handy CLI Commands

Command	Action
list-jobs	Prints the job names
build my-job	Starts a build
build my-job -s -v	Starts a build, waits, and shows the log
console my-job	Shows the latest console output
get-job my-job	Prints the job configuration as XML
create-job new-job	Creates a job from XML sent on standard input
safe-restart	Restarts Jenkins after running builds finish

java -jar jenkins-cli.jar -s https://jenkins.example.com/ \
     -auth admin:YOUR_API_TOKEN build nightly-report -s -v

How the REST API Is Organised

Almost every Jenkins page has an API twin. Add /api/json to the page address and Jenkins returns data instead of a web page.

 Web page                                  API version
 ---------------------------------------   -----------------------------------------------
 /job/my-job/                              /job/my-job/api/json
 /job/my-job/42/                           /job/my-job/42/api/json
 /                                         /api/json

curl -s -u admin:YOUR_API_TOKEN \
     https://jenkins.example.com/job/my-job/lastBuild/api/json

The reply holds fields such as result, duration, number, and timestamp. Use the tree parameter to request only what you need:

curl -s -u admin:YOUR_API_TOKEN \
     "https://jenkins.example.com/job/my-job/lastBuild/api/json?tree=result,duration"

Starting Builds Through the API

# Build without parameters
curl -X POST -u admin:YOUR_API_TOKEN \
     https://jenkins.example.com/job/my-job/build

# Build with parameters
curl -X POST -u admin:YOUR_API_TOKEN \
     "https://jenkins.example.com/job/my-job/buildWithParameters?ENV=staging&VERSION=1.4.2"

Jenkins answers with status 201 and a Location header. The header points to a queue item, which you can poll to learn when the build begins.

The Request Flow

 Script ---- HTTPS + token ----> Jenkins
   |                                |
   |<--- 201 Created + queue URL ---+
   |
   |---- GET queue item ----------> Jenkins
   |<--- build number ---------------+
   |
   |---- GET build api/json ------> Jenkins
   |<--- result: SUCCESS -----------+

A Simple Status Script

#!/bin/bash
JENKINS="https://jenkins.example.com"
AUTH="admin:YOUR_API_TOKEN"
RESULT=$(curl -s -u "$AUTH" "$JENKINS/job/my-job/lastBuild/api/json?tree=result" \
         | python3 -c "import sys, json; print(json.load(sys.stdin)['result'])")
echo "Last build result: $RESULT"

Security Notes

• Use HTTPS so tokens never cross the network in clear text.
• Create one token per tool, then revoke tokens that are no longer used.
• Give automation users only the permissions the task needs.
• Keep tokens out of shell history and logs.

Troubleshooting

Response	Meaning and Fix
401 Unauthorized	Wrong user or token. Generate a new token
403 Forbidden	User lacks permission, or a proxy blocks the call
404 Not Found	Job path wrong. Folders need /job/folder/job/name
Connection refused	Wrong host or port, or Jenkins is down

With a token and curl, you can connect Jenkins to almost any other tool in your toolbox.

Ideas for Real Projects

Connect a chat bot that starts a deployment when a teammate types a command. Build a wall dashboard that reads the latest result of every job and shows green and red tiles. Write a nightly script that lists jobs without a recent successful build and emails the owners. Each idea needs only a token and a few lines of curl, and each one removes a repeated manual task from your week.