jiractl: A command-line tool for managing Jira
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!
