EngineeringCategory

jiractl: A command-line tool for managing Jira

5 min read
Emma LubinGabe IsenbergJon YonkerOliver ColbertSam Hughes
A foosball table game

At GoDaddy we use Jira to track and manage our projects. Jira has an extensive feature set that can be customized to different teams’ needs, but its customizability can make it difficult for developers to perform simple tasks during a sprint. Visiting the Jira UI to check sprint progress or update an issue takes a developer out of their normal workflow on the command line. During a recent hackathon, we decided to address this problem by building an opensource Jira CLI for managing our sprints.

There are a number of other Jira CLIs already out there; Atlassian sells one, there are a handful of opensource node-based Jira CLIs – for example, jira-node-cli, jira-console, and JiraTool – and go-jira, a highly-starred tool written in Go.

We found existing tools that met some of our needs, but decided to contribute our own to ensure we could support all of our common use cases and requirements:

  • Easy management of multiple teams
  • Intuitive, context-based syntax
  • Board, epic, sprint, and issue views
  • Issue creation from template files

Features

Support for multiple teams – One engineering group at GoDaddy might have multiple scrum teams each with their own Jira boards. We wanted to make it easy to manage and switch between boards within a project. After installing jiractl you can add a context for the Jira instance you use and fetch teams configured within that instance. For example, for GoDaddy:

$ npm i @godaddy/jiractl -g
$ jiractl config set-context https://jira.godaddy.com
Username: foo
Password:
Context "https://jira.godaddy.com" created.
Set default context to "https://jira.godaddy.com".

To view teams in a Jira project, run:

$ jiractl get teams { Jira Project Key }
ID  	  TYPE      NAME
1	  scrum     Cats
2	  kanban    Sharks

Intuitive syntax – Our developers use Kubernetes and kubectl, which allows users to set a context and then perform actions within that context; we wanted to emulate that syntax in our tool since it’s familiar to developers, making adoption easier, and more importantly since it reflects how we use Jira: performing a set of actions (e.g., viewing past sprint velocities) within a context (e.g., Jira board). Like kubectl, jiractl uses the get action to give an overview of a resource, and describe to provide detailed insight.

For example, you can get a team’s epics by running:

$ jiractl --team=1 get epics
Epic:
KEY		SUMMARY
GX-4019 	Build Experimentation Platform
GX-5212 	Self-service A/B results dashboard
GX-5589 	Add NPS Scoring

And fetch details with:

$ jiractl --team=1 describe epics
Epic:
KEY	SUMMARY						COMPLETED/TOTAL POINTS
GX-4019	Build Experimentation Platform			10/10

Stories:
KEY	STATUS	SUMMARY					POINTS
GX-6337	Closed 	As a PO ISBAT stop an experiment	5
GX-7014	Closed 	As a PO ISBAT start an experiment       5

Epic:
KEY	SUMMARY						COMPLETED/TOTAL POINTS
GX-5212	Self-service A/B results dashboard		0/5

Stories:
KEY	STATUS	SUMMARY					POINTS
GX-1952	Open 	As a PO ISBAT view experiment results   5

Epic:
KEY	SUMMARY						COMPLETED/TOTAL POINTS
GX-4099	Add NPS Scoring					8/8

Stories:
KEY	STATUS	SUMMARY					POINTS
GX-6337	Closed 	ISBAT measure NPS		    	8

Multiple views – Many of the existing tools we saw were crafted around an issue-based workflow, but we wanted one that would let us run an entire sprint planning or backlog refinement session from the command line. Others had more of the features we were looking for but were still in the early stages of development. To fulfill our use cases, we wanted jiractl users to be able to answer questions like “What was my team’s velocity over the past few sprints?” and “What epics do we have ready?” We found those were easiest to answer by configuring different commands for each of those views.

In addition to the team and epic views shown above, you can see a team’s sprints by running:

$ jiractl --team=1 get sprints
ID   	  STATE    NAME			VELOCITY
18669	  active   Sprint 5/7-5/18     	0
18471	  closed   Sprint 4/23-5/4     	54
18264	  closed   Sprint 4/9-4/20   	62

To get a sprint by id:

$ jiractl --team=1 get sprint { sprint_id }
NAME               STARTDATE				ENDDATE				COMPLETED/TOTAL POINTS
Sprint 5/7-5/18    2018-05-07T09:33:33.302-07:00	2018-05-18T17:40:00.000-07:00	8/13

Members: Gabriel Isenberg, Jon Yonker

Issues:
KEY		STATUS		SUMMARY			     POINTS
GX-1199		In Progress     Add auth to dashboard        5
GX-1198		Closed     	Dockerize dashboard repo     8

Issue creation (under development) – One feature in particular that was hard to find in existing tools was issue creation from template files. We’ve found writing stories in a text editor to be faster than filling out fields in the Jira UI. We’d like developers to be able to fill in a Jira template stored in GitHub and run a jiractl command to upload it. This workflow would also ensure our stories follow a set, peer-reviewed format, without needing to copy template issues in the Jira UI. We’re working on adding this feature to jiractl soon, but for now, you can retrieve and update existing issues using jiractl.

To update an issue:

$ jiractl update issue { issue_key } --points=8 --assignee=foo

What’s next?

We’ve already started using this in some of our teams, but to meet our goal of sprint planning and refinement on the command line we’ll continue adding features like voting on story points and creating new sprints.

Have you tried it out? Would you like to contribute? You can file GitHub issues to propose new features here!