Awesome Open Source
Awesome Open Source
stargazers over time

JiraCLI

Build GO Report-card Software License Software License

Feature-rich Interactive Jira Command Line

JiraCLI Demo

🚧 This project is still a work in progress 🚧
jira-cli open collective badge

JiraCLI is a command line tool for Jira created with an idea to avoid the Jira UI as much as possible. The tool is not yet complete but has all necessary features required to improve your workflow with Jira. The tool mostly focuses on issue search and navigation at the moment. However, it also includes features like issue creation, cloning, linking, ticket transition, and so on.

Your suggestions and feedbacks are highly appreciated. Feel free to start a discussion or create an issue to share your experience about the tool or to discuss a feature/issue. If you think this project is cool and helpful, consider contributing by starring the repo, sharing with your friends or submitting a PR.

Supported platforms

The tool is only tested with the latest Jira cloud since that's what I usually work with. There is a plan to support local Jira instances in the future, however, it might not happen anytime soon.

Platform Software LicenseSoftware LicenseSoftware License
Jira Software LicenseSoftware License

Installation

Install the runnable binary to your $GOPATH/bin.

go get github.com/ankitpokhrel/jira-cli/cmd/jira

Releases and other installation options will be available later.

Getting started

  1. Get a Jira API token and export it to your shell as a JIRA_API_TOKEN variable. Add it to your shell configuration file, for instance, $HOME/.bashrc, so that the variable is always available.
  2. Run jira init to generate a config file required for the tool.

Shell completion

Check jira completion --help for more info on setting up a bash/zsh shell completion.

Usage

The tool currently comes with an issue, epic, and sprint explorer. The flags are POSIX-compliant. You can combine available flags in any order to create a unique query. For example, the command below will give you high priority issues created this month with status To Do that are assigned to you and has a label backend.

jira issue list -yHigh -s"To Do" --created month -lbackend -a$(jira me)

Navigation

The lists are displayed in an interactive UI by default.

  • Use arrow keys or j, k, h, l characters to navigate through the list.
  • Use g and SHIFT+G to quickly navigate to the top and bottom respectively.
  • Press v to view selected issue details.
  • Hit ENTER to open the selected issue in the browser.
  • Press c to copy issue URL to the system clipboard. This requires xclip / xsel in linux.
  • Press CTRL+K to copy issue key to the system clipboard.
  • In an explorer view, press w to toggle focus between the sidebar and the contents screen.
  • Press q / ESC / CTRL+C to quit.

Commands

Issue

Issues are displayed in an interactive table view by default. You can output the results in a plain view using the --plain flag.

List

The list command lets you search and navigate the issues.

# List recent issues
$ jira issue list

# List issues created in last 7 days
$ jira issue list --created -7d

# List issues in status "To Do"
$ jira issue list -s"To Do"

# List recent issues in plain mode
$ jira issue list --plain

# You can execute raw JQL within a given project context using `--jql/-q` option.
# For instance, the following command will list issues in current project whose
# summary has a word cli.
$ jira issue list -q "summary ~ cli"

Check some more examples/use-cases below.

List issues that I am watching
jira issue list -w
List issues assigned to me
jira issue list -a$(jira me)
List issues assigned to a user and are reported by another user
jira issue list -a"User A" -r"User B"
List issues assigned to me is of high priority and is open
jira issue list -a$(jira me) -yHigh -sopen
List issues assigned to no one and are created this week
jira issue list -ax --created week
List issues with resolution won't do
jira issue list -R"Won't do"
List issues whose status is not done and is created before 6 months and is assigned to someone
# Tilde (~) acts as a not operator
jira issue list -s~Done --created-before -24w -a~x
List issues created within an hour and updated in the last 30 minutes ⏱
jira issue list --created -1h --updated -30m
Give me issues that are of high priority, is in progress, was created this month, and has given labels 🔥
jira issue list -yHigh -s"In Progress" --created month -lbackend -l"high prio"
Wait, what was that ticket I opened earlier today? 😫
jira issue list --history
What was the first issue I ever reported on the current board? 🤔
jira issue list -r$(jira me) --reverse
What was the first bug I ever fixed in the current board? 🐞
jira issue list -a$(jira me) -tBug sDone -rFixed --reverse
What issues did I report this week? 🤷‍♂️
jira issue list -r$(jira me) --created week
Am I watching any tickets in project XYZ? :monocle_face:
jira issue list -w -pXYZ

Create

The create command lets you create an issue.

# Create an issue using interactive prompt
$ jira issue create

# Pass required parameters to skip prompt or use --no-input option
$ jira issue create -tBug -s"New Bug" -yHigh -lbug -lurgent -b"Bug description"

Create an issue

The command supports both Github-flavored and Jira-flavored markdown for writing description. You can load pre-defined templates using --template flag.

# Load description from template file
$ jira issue create --template /path/to/template.tmpl

# Get description from standard input
$ jira issue create --template -

# Or, use pipe to read input directly from standard input
$ echo "Description from stdin" | jira issue create -s"Summary" -tTask

Markdown render preview

The preview above shows markdown template passed in Jira CLI and how it is rendered in the Jira UI.

Assign

The assign command lets you assign user to an issue.

# Assign user to an issue using interactive prompt
$ jira issue assign

# Pass required parameters to skip prompt
$ jira issue assign ISSUE-1 "Jon Doe"

# Assign to self
$ jira issue assign ISSUE-1 $(jira me)

# Will prompt for selection if keyword suffix returns multiple entries
$ jira issue assign ISSUE-1 suffix

# Assign to default assignee
$ jira issue assign ISSUE-1 default

# Unassign
$ jira issue assign ISSUE-1 x

Assign issue to a user

Move/Transition

The move command lets you transition issue from one state to another.

# Move an issue using interactive prompt
$ jira issue move

# Pass required parameters to skip prompt
$ jira issue move ISSUE-1 "In Progress"

Move an issue

View

The view command lets you see issue details in a terminal. Atlassian document is roughly converted to a markdown and is nicely displayed in the terminal.

$ jira issue view ISSUE-1

View an issue

Link

The link command lets you link two issues.

# Link an issue using interactive prompt
$ jira issue link

# Pass required parameters to skip prompt
$ jira issue link ISSUE-1 ISSUE-2 Blocks

Clone

The clone command lets you clone an issue. You can update fields like summary, priority, assignee, labels, and components when cloning the issue. The command also allows you to replace a part of the string (case-sensitive) in summary and description using --replace/-H option.

# Clone an issue
$ jira issue clone ISSUE-1

# Clone issue and modify the summary, priority and assignee
$ jira issue clone ISSUE-1 -s"Modified summary" -yHigh -a$(jira me)

# Clone issue and replace text from summary and description
$ jira issue clone ISSUE-1 -H"find me:replace with me"

Comment

The comment command provides a list of sub-commands to manage issue comments.

Add

The add command lets you add comment to an issue. The command supports both Github-flavored and Jira-flavored markdown for writing comment. You can load pre-defined templates using --template flag.

# Add a comment using interactive prompt
$ jira issue comment add

# Pass required parameters to skip prompt
$ jira issue comment add ISSUE-1 "My comment body"

# Load comment from template file
$ jira issue comment add ISSUE-1 --template /path/to/template.tmpl

# Get comment from standard input
$ jira issue comment add ISSUE-1 --template -

# Or, use pipe to read input directly from standard input
$ echo "Comment from stdin" | jira issue comment add ISSUE-1

Epic

Epics are displayed in an explorer view by default. You can output the results in a table view using the --table flag. When viewing epic issues, you can use all filters available for the issue command.

See usage to learn more about UI interaction.

List

You can use all flags supported by issue list command here except for the issue type.

# List epics
$ jira epic list

# List epics in a table view
$ jira epic list --table

# List epics reported by me and are open
$ jira epic list -r$(jira me) -sOpen

# List issues in an epic
$ jira epic list KEY-1

# List all issue in an epic KEY-1 that is unassigned and has a high priority
$ jira epic list KEY-1 -ax -yHigh

# List high priority epics
$ jira epic list KEY-1 -yHigh

Create

Creating an epic is same as creating the issue except you also need to provide an epic name.

# Create an issue using interactive prompt
$ jira epic create

# Pass required parameters to skip prompt or use --no-input flag to skip prompt for non-mandatory params
$ jira epic create -n"Epic epic" -s"Everything" -yHigh -lbug -lurgent -b"Epic description"

Add

Add command allows you to add issues to the epic. You can add up to 50 issues to the epic at once.

# Add issues to the epic using interactive prompt
$ jira epic add

# Pass required parameters to skip prompt
$ jira epic add EPIC-KEY ISSUE-1 ISSUE-2

Remove

The remove command allows you to remove issues from the epic. You can remove up to 50 issues from the epic at once.

# Remove issues to the epic using interactive prompt
$ jira epic remove

# Pass required parameters to skip prompt
$ jira epic remove ISSUE-1 ISSUE-2

Sprint

Sprints are displayed in an explorer view by default. You can output the results in a table view using the --table flag. When viewing sprint issues, you can use all filters available for the issue command. The tool only shows 25 recent sprints.

See usage to learn more about UI interaction.

# List sprints in an explorer view
$ jira sprint list

# List sprints in a table view
$ jira sprint list --table

# List issues in current active sprint
$ jira sprint list --current

# List issues in current active sprint that are assigned to me
$ jira sprint list --current -a$(jira me)

# List issues in previous sprint
$ jira sprint list --prev

# List issues in next planned sprint
$ jira sprint list --next

# List future and active sprints
$ jira sprint list --state future,active

# List issues in a particular sprint. You can use all flags supported by issue list command here.
# To get sprint id use `jira sprint list` or `jira sprint list --table`
$ jira sprint list SPRINT_ID

# List high priority issues in a sprint are assigned to me
$ jira sprint list SPRINT_ID -yHigh -a$(jira me)

Other commands

Navigate to the project
jira open
Navigate to the issue
jira open KEY-1
List all projects you have access to
jira project
List all boards in a project
jira board

Scripts

Often times, you may want to use the output of the command to do something cool. However, the default interactive UI might not allow you to do that. The tool comes with the --plain flag that displays results in a simple layout that can then be manipulated from the shell script.

Some example scripts are listed below.

Tickets created per day this month
#!/usr/bin/env bash

tickets=$(jira issue list --created month --plain --columns created --no-headers | awk '{print $1}' | awk -F'-' '{print $3}' | sort -n | uniq -c)

echo "${tickets}" | while IFS=$'\t' read -r line; do
  day=$(echo "${line}" | awk '{print $2}')
  count=$(echo "${line}" | awk '{print $1}')

  printf "Day #%s: %s\n" "${day}" "${count}"
done

# Output
Day #01: 19
Day #02: 10
Day #03: 21
...
Number of tickets per sprint
#!/usr/bin/env bash

sprints=$(jira sprint list --table --plain --columns id,name --no-headers)

echo "${sprints}" | while IFS=$'\t' read -r id name; do
  count=$(jira sprint list "${id}" --table --plain --no-headers 2>/dev/null | wc -l)

  printf "%10s: %3d\n" "${name}" $((count))
done

# Output
Sprint 3:   55
Sprint 2:   40
Sprint 1:   30
...
Number of unique assignee per sprint
#!/usr/bin/env bash

sprints=$(jira sprint list --table --plain --columns id,name --no-headers)

echo "${sprints}" | while IFS=$'\t' read -r id name; do
  count=$(jira sprint list "${id}" --table --plain --columns assignee --no-headers 2>/dev/null | sort -n | uniq | wc -l)

  printf "%10s: %3d\n" "${name}" $((count))
done

# Output
Sprint 3:   5
Sprint 2:   4
Sprint 1:   3

Development

  1. Clone the repo.

    git clone [email protected]:ankitpokhrel/jira-cli.git
    
  2. Make changes, build the binary, and test your changes.

    make deps install
    
  3. Run CI steps locally before submitting a PR.

    make ci
    

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
go (15,319
golang (3,947
cli (1,826
command-line (547
command-line-tool (298
tui (159
cli-app (108
jira (50
terminal-app (39