yojenkins — A User-Friendly Command Line Interface Tool for Jenkins

Published in

AWS Tip

6 min readFeb 28, 2022

The purpose of this article is to introduce and outline yojenkins, a command line interface (CLI) tool used to interface with and manage one or multiple Jenkins servers.

Introduction

I have been working Jenkins servers for some time now. Jenkins can be great automation tool, helping teams with building, testing, deploying, etc. However, beyond the simple clicking and scrolling in the web browser based Jenkins UI, Jenkins can become a little a hairy, leaving you endlessly scrolling through a never-ending supply of Stackoverflow articles, GitHub gists, Jenkins docs.

I always wanted a tool that is something more clear and efficient when interacting with Jenkins. Knowing how efficient terminal tools can be, I also wanted something more fitting for the terminal. But there didn’t seem to be such a thing.

While there are some great and clever scripts that interact with Jenkins in a specific way, they are scattered all around the internet in various different ways.

For example, try programmatically creating a user account and adding specific permissions to that account. You will find a few different documentation sources doing that a few different things with a combination of a few different programming languages.

While yojenkins did start as small bite-sized scripts, I finally aggregated these to make a more comprehensive and user-friendly CLI tool

I really hope you will use and enjoy this new tool and it makes you more efficient working with Jenkins server.

Jenkins and Existing Jenkins Tools

Jenkins server is a great open source Continuous Integration/Continuous Deployment (CI/CD) tool used by much of the DevOps industry for various software automation tasks. These automation tasks range from running stand-alone scripts at some time interval, to deploying an automatically triggered multi-cloud infrastructure, and much more. Essentially Jenkins is a server that will simply execute the things you tell it to.

Once set up, there are a few different ways someone can interface or communicate with a Jenkins server.

Jenkins web browser user interface — Using the web UI is the most common and most documented way of interacting with Jenkins. While it allows for a pretty visual UI with the ability to point/click/scroll/etc, the experience can be dependent on browser performance.
REST API — This is a more automated approach that can be used in an agnostic way to send HTTP based calls to Jenkins and receiving JSON responses back.
3rd-Party Software Development Kits (SDKs) — In order to package Jenkins REST API calls in a more usable way, this approach wraps calls to Jenkins in programming language specific building blocks for programmers to use in their code (i.e. Python Jenkins)
Official Jenkins CLI — Jenkins provides a CLI allowing access for scripting or troubleshooting. While this Java-based CLI offers some great tools, it is not very user friendly, intuitive, and does not provide the greatest documentation. In essence, this CLI tool seems to be targeted more towards scripting.

In most non-terminal based situations, and for a good amount of users, these interaction methods are sufficient enough to do whatever needs to be done with Jenkins. However, it seems to be impossible to interact with Jenkins from the terminal in a simple human-friendly manor similar to other common CLI tools (i.e. AWS CLI, docker, etc.)

yojenkins

yojenkins tries to do what the other approaches do, but inside the terminal and in more intuitive and user-friendly way.

It enables users to quickly do simple or complicated Jenkins tasks from the terminal or programmatically integrated into a script.

The following sections will discuss the installation, setup, and some simple usage of yojenkins.

Installation

For Ubuntu or CentOS we need to install a few system dependencies mainly needed for its sound notification abilities. MacOS and Windows do not need this step.

Ubuntu- sudo apt update && apt-get install -y python3-dev python3-pip libasound2-dev
Centos — sudo yum update && yum install -y python3-devel gcc alsa-lib-devel

While there are a few different installation option, we are going to download and install yojenkins from Python Package Index (PYPI) with pip.

pip install yojenkins

Verify the installation by simply entering yojenkins

$ yojenkins

Usage: yojenkins [OPTIONS] COMMAND [ARGS]...

                   YOJENKINS (Version: 0.0.0)

yojenkins is a tool that is focused on interfacing with Jenkins server from the comfort of the beloved command line. This tool can also be used as a middleware utility, generating and passing Jenkins information or automating tasks.

QUICK START:

  1. Configure yo profile: yojenkins auth configure
  2. Add yo API token:     yojenkins auth token --profile <PROFILE>
  3. Verify yo creds:      yojenkins auth verify
  4. Explore yojenkins

Options:
  -v, --version  Show the version
  --help         Show this message and exit.

Commands:
  account     Manage user accounts
  auth        Manage authentication and profiles
  build       Manage builds
  credential  Manage credentials
  folder      Manage folders
  job         Manage jobs
  node        Manage nodes
  server      Manage server
  stage       Manage build stages
  step        Manage stage steps
  tools       Tools and more

(Optional) Local Jenkins Server Setup with Docker

If you don’t have a Jenkins server to mess around with, but still want to try out yojenkins, that’s ok, yojenkins is able to quickly spin up a full-fledged Jenkins server running in a local Docker container.

Ensure that Docker is installed and running on your computer, and run the following command. Note that the first time may take a minute for Docker to download the Jenkins image.

yojenkins server server-deploy

If all is well, you should see something like the following output.

$ yojenkins server server-deploySetting up a local Jenkins development server. Hold tight, this may take a minute ...Successfully created containerized Jenkins server!
   - Docker image:      yojenkins-jenkins:latest
   - Docker volumes:    yojenkins-jenkins
   - Docker container:  yojenkins-jenkins
   - Deployment file:   C:\Users\ismet\.yojenkins\last_deploy_info.jsonAddress:  http://localhost:8080
Username: admin
Password: password (default)

You can open up your web browser and navigate to the given address (http://localhost:8080) before logging in using the provided credentials (admin/password).

Note, after you are done with tinkering with yojenkins and this local Jenkins server, you can remove remove this server deployment with the following command.

yojenkins server server-teardown

Authentication Setup

After a successful installation, it is possible to use yojenkins as-is, however, at each command, it will prompt for credential information, which is not very convenient.

A way that yojenkins makes Jenkins interaction seamless is with setting up authentication profiles. Essentially, it keeps a local file with credential information, which it reads when entering a yojenkins command. This method is very similar to the local credential file kept by AWS CLI.

To set up an authentication profile enter the following command.

yojenkins auth configure

yojenkins will in turn ask for some information to set up your first authentication profile.

$ yojenkins auth configureCredentials profile file (credentials) NOT found in configuration directory
Creating a new credentials file: C:\Users\ismet\.yojenkins\credentials ...
Please enter the following information to create your first profile entry:[ OPTIONAL ] Enter PROFILE NAME (default):
[ REQUIRED ] Enter Jenkins SERVER BASE URL:  http://localhost:8080
[ REQUIRED ] Enter USERNAME:  adminSuccessfully configured credentials file

Now that we have the default authentication profile set up, let’s add a new server API token to this profile.

yojenkins auth token --profile default

After entering your Jenkins server password into the prompt, the new API token will automatically be added to your profile.

Verify your server authentication with the default profile.

yojenkins auth verify

Usage Demo

Although there are many more yojenkins operations we can do, here we are only going to do a few simple Jenkins tasks.

Important: You must have appropriate Jenkins user permissions to perform these actions on the server.

Get information about own user account in formatted JSON
yojenkins auth user --pretty
Create a folder in the Jenkins top level directory (note the .)
yojenkins folder create --type folder "My Demo Folder" .
Create a blank job in the new folder
yojenkins job create “My First Job” “My Demo Folder”
Get information about this new job in YAML format
yojenkins job info “My Demo Folder/My First Job” --yaml
Get a list of all items (folders, views, jobs) within the folder
yojenkins folder items “My Demo Folder” --pretty --list
Build the job
yojenkins job build “My Demo Folder/My First Job”
Get the build logs
yojenkins build logs “My Demo Folder/My First Job” --latest
Delete the entire folder that was created
yojenkins folder delete “My Demo Folder”

I think these operations will give you the idea how the tool behaves. For more complex operations, explore the CLI menu and review the documentation.

I hope you enjoyed exploring yojenkins!

More Resources

For more information, documentation, and examples visit yojenkins.com. Also check out the yojenkins public GitHub repository to view the code, contribute to this project, submit bug reports, request features, etc.