Published 2022-08-12.
Time to read: 2 minutes.
This page is part of the
posts collection, categorized under Open Source.
When first released in 2002, Jira was merely a bug tracker. Since then, it has gained features and is now used as a project management tool. But that does not mean Jira users like the product.
Jira only provides a web user interface, which cannot be scripted.
Jira is available as a free cloud plan that is free forever for small teams of up to 10 users. It includes 2 GB of storage, basic features for software development (boards, backlogs), and community support. This plan is designed for small projects and does not require a credit card to start. This free plan is responsible for the popularity of Jira.
JiraCLI, an independent F/OSS project, provides command-line explorers for Jira projects, boards, epics, issues, and sprints.
Because the majority of expert witness cases that come to me use Jira, I need to pull project information from it. The best type tool for that purpose is a command-line interface (CLI), because those types of programs can be scripted.
Installation
JiraCLI is a Go program, so it is quick and easy to install on Ubuntu once Go is installed. I find Go programs easy to manage.
Shell
$ yes | sudo apt install golang-go
$ go install github.com/ankitpokhrel/jira-cli/cmd/jira@latest go: downloading github.com/ankitpokhrel/jira-cli v1.7.0 go: downloading github.com/zalando/go-keyring v0.2.6 go: downloading github.com/cli/safeexec v1.0.1 go: downloading github.com/kballard/go-shellquote v0.0.0-20180428030007-95032a82bc51 go: downloading github.com/spf13/viper v1.18.2 go: downloading github.com/AlecAivazis/survey/v2 v2.3.7 go: downloading github.com/gdamore/tcell/v2 v2.7.4 go: downloading github.com/rivo/tview v0.0.0-20240406141410-79d4cc321256 go: downloading github.com/mgutz/ansi v0.0.0-20200706080929-d51e80ef957d go: downloading github.com/charmbracelet/glamour v0.9.1 go: downloading github.com/briandowns/spinner v1.23.2 go: downloading github.com/mitchellh/go-homedir v1.1.0 go: downloading github.com/kentaro-m/blackfriday-confluence v0.0.0-20220126124413-8e85477b49b3 go: downloading golang.org/x/term v0.30.0 go: downloading github.com/russross/blackfriday/v2 v2.1.0 go: downloading github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c go: downloading golang.org/x/sys v0.31.0 go: downloading github.com/mattn/go-colorable v0.1.14 go: downloading github.com/cpuguy83/go-md2man/v2 v2.0.3 go: downloading golang.org/x/text v0.23.0 go: downloading github.com/fsnotify/fsnotify v1.7.0 go: downloading github.com/pelletier/go-toml/v2 v2.2.0 go: downloading github.com/gdamore/encoding v1.0.1 go: downloading github.com/yuin/goldmark v1.7.8 go: downloading github.com/yuin/goldmark-emoji v1.0.5 go: downloading github.com/alecthomas/chroma/v2 v2.15.0 go: downloading github.com/microcosm-cc/bluemonday v1.0.27 go: downloading github.com/charmbracelet/x/ansi v0.8.0 go: downloading github.com/muesli/reflow v0.3.0 go: downloading github.com/aymerick/douceur v0.2.0 go: downloading golang.org/x/net v0.38.0 go: downloading github.com/dlclark/regexp2 v1.11.5 go: downloading github.com/gorilla/css v1.0.1
Add $HOME/go/bin to the PATH so jira can be found:
Shell
$ echo 'PATH=$HOME/go/bin:$PATH' >> ~/.bashrc
$ source ~/.bashrc
$ which jira /home/mslinn/go/bin/jira
Usage
This is the jira help message:
Shell
$ jira Interactive Jira CLI.
USAGE jira [flags]
MAIN COMMANDS board Board manages Jira boards in a project epic Epic manage epics in a project issue Issue manage issues in a project open Open issue in a browser project Project manages Jira projects sprint Sprint manage sprints in a project board
OTHER COMMANDS completion Output shell completion code for the specified shell (bash or zsh) help Help about any command init Init initializes jira config man Help generate man(7) pages for Jira CLI. me Displays configured jira user version Print the app version information
FLAGS -c, --config string Config file (default is /home/mslinn/.config/.jira/.config.yml) --debug Turn on debug output -h, --help help for jira -p, --project string Jira project to look into (defaults to /home/mslinn/.config/.jira/.config.yml)
LEARN MORE Use 'jira <command> <subcommand> --help' for more information about a command.
You need an Jira API token before you can use JiraCLI. Get it from here.
You need to configure the program before you use it.
Set the JIRA_API_TOKEN environment variable before running jira init.
If you do not, then you will get an error like
Received unexpected response '401 Unauthorized' from jira. in the next step.
Shell
$ export JIRA_API_TOKEN=asdfasdfasdf $ jira init ? Installation type: Cloud ? Link to Jira server: https://xxx.atlassian.net/ ? Login email: mslinn@mslinn.com ⠼ Verifying login details... ? Default project: My ? Default board: [Use arrows to move, type to filter, ? for more help] > [Search...] ---------- My Scrum Board None ✓ Configuration generated: /home/mslinn/.config/.jira/.config.yml
This is the configuration file that was generated:
/home/mslinn/.config/.jira/.config.yml/
board:
id: 350
name: My Scrum Board
type: scrum
epic:
name: customfield_10009
link: customfield_10008
installation: Cloud
issue:
fields:
custom:
- name: Epic Link
key: customfield_10008
schema:
datatype: any
- name: Epic Name
key: customfield_10009
schema:
datatype: string
types:
- id: "3"
name: Task
handle: Task
subtask: false
- id: "5"
name: Sub-task
handle: Sub-task
subtask: true
- id: "7"
name: Story
handle: Story
subtask: false
- id: "1"
name: Bug
handle: Bug
subtask: false
- id: "6"
name: Epic
handle: Epic
subtask: false
login: mslinn@mslinn.com
project:
key: My
type: classic
server: https://xxx.atlassian.net
Example Commands
As an expert witness, my job is to perform software archaeology, without disturbing the project. Thus I must only have read access to projects, so I am unable to accidently modify anything. The following Jira CLI subcommands are the only ones I need to do my job:
Help for the jira project subcommand:
Shell
$ jira project -h Project manages Jira projects. See available commands below.
USAGE jira project [flags]
MAIN COMMANDS list List lists Jira projects
FLAGS -h, --help help for project
INHERITED FLAGS -c, --config string Config file (default is /home/mslinn/.config/.jira/.config.yml, can be overridden with JIRA_CONFIG_FILE env var) --debug Turn on debug output -p, --project string Jira project to look into (defaults to /home/mslinn/.config/.jira/.config.yml)
ALIASES projects
LEARN MORE Use 'jira <command> <subcommand> --help' for more information about a command. Read the doc or get help at https://github.com/ankitpokhrel/jira-cli
Help for the jira board subcommand:
Shell
$ jira board -h Board manages Jira boards in a project. See available commands below.
USAGE jira board [flags]
MAIN COMMANDS list List lists boards in a project
FLAGS -h, --help help for board
INHERITED FLAGS -c, --config string Config file (default is /home/mslinn/.config/.jira/.config.yml, can be overridden with JIRA_CONFIG_FILE env var) --debug Turn on debug output -p, --project string Jira project to look into (defaults to /home/mslinn/.config/.jira/.config.yml)
ALIASES boards
LEARN MORE Use 'jira <command> <subcommand> --help' for more information about a command. Read the doc or get help at https://github.com/ankitpokhrel/jira-cli
Help for the jira epic subcommand:
Shell
$ jira epic -h Epic manage epics in a given project. See available commands below.
USAGE jira epic [flags]
MAIN COMMANDS add Add issues to an epic create Create an epic in a project list List lists issues in a project remove Remove/unassign epic from issues
FLAGS -h, --help help for epic
INHERITED FLAGS -c, --config string Config file (default is /home/mslinn/.config/.jira/.config.yml, can be overridden with JIRA_CONFIG_FILE env var) --debug Turn on debug output -p, --project string Jira project to look into (defaults to /home/mslinn/.config/.jira/.config.yml)
ALIASES epics
LEARN MORE Use 'jira <command> <subcommand> --help' for more information about a command. Read the doc or get help at https://github.com/ankitpokhrel/jira-cli
Help for the jira open subcommand:
Shell
$ jira open -h Open opens issue in a browser. If the issue key is not given, it will open the project page.
USAGE jira open [ISSUE-KEY] [flags]
FLAGS -h, --help help for open -n, --no-browser Skip opening destination URL in the browser
INHERITED FLAGS -c, --config string Config file (default is /home/mslinn/.config/.jira/.config.yml, can be overridden with JIRA_CONFIG_FILE env var) --debug Turn on debug output -p, --project string Jira project to look into (defaults to /home/mslinn/.config/.jira/.config.yml)
ARGUMENTS [ISSUE-KEY] Issue key, eg: ISSUE-1
EXAMPLES $ jira open $ jira open ISSUE-1
ALIASES browse navigate
LEARN MORE Use 'jira <command> <subcommand> --help' for more information about a command. Read the doc or get help at https://github.com/ankitpokhrel/jira-cli
Help for the jira issue subcommand:
Shell
$ jira issue -h Issue manage issues in a given project. See available commands below.
USAGE jira issue [flags]
MAIN COMMANDS assign Assign issue to a user clone Clone duplicates an issue comment Manage issue comments create Create an issue in a project delete Delete an issue edit Edit an issue in a project link Link connects two issues list List lists issues in a project move Transition an issue to a given state unlink Unlink disconnects two issues from each other view View displays contents of an issue worklog Manage issue worklog
FLAGS -h, --help help for issue
INHERITED FLAGS -c, --config string Config file (default is /home/mslinn/.config/.jira/.config.yml) --debug Turn on debug output -p, --project string Jira project to look into (defaults to /home/mslinn/.config/.jira/.config.yml)
ALIASES issues
LEARN MORE Use 'jira <command> <subcommand> --help' for more information about a command.
Help for the jira issue list sub-subcommand:
Shell
$ jira issue list -h List lists issues in a given project.
You can combine different flags to create a unique query. For instance,
# 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"
You can also add an optional search query as a positional argument, which functions the same as entering a search query into the Jira UI's search box.
Issues are displayed in an interactive list view by default. You can use a --plain flag to display output in a plain text mode. A --no-headers flag will hide the table headers in plain view. A --no-truncate flag will display all available fields in plain mode.
USAGE jira issue list [optional text to query] [flags]
FLAGS -t, --type string Filter issues by type -R, --resolution string Filter issues by resolution type -s, --status stringArray Filter issues by status -y, --priority string Filter issues by priority -r, --reporter string Filter issues by reporter (email or display name) -a, --assignee string Filter issues by assignee (email or display name) -C, --component string Filter issues by component -l, --label stringArray Filter issues by label -P, --parent string Filter issues by parent --history Issues you accessed recently -w, --watching Issues you are watching --created string Filter issues by created date Accepts: today, week, month, year, or a date in yyyy-mm-dd and yyyy/mm/dd format, or a period format using w = weeks, d = days, h = hours, m = minutes. eg: -10d Created filter will have precedence over created-after and created-before filter --updated string Filter issues by updated date Accepts: today, week, month, year, or a date in yyyy-mm-dd and yyyy/mm/dd format, or a period format using w = weeks, d = days, h = hours, m = minutes. eg: -10d Updated filter will have precedence over updated-after and updated-before filter --created-after string Filter by issues created after certain date --updated-after string Filter by issues updated after certain date --created-before string Filter by issues created before certain date --updated-before string Filter by issues updated before certain date -q, --jql string Run a raw JQL query in a given project context --order-by string Field to order the list with (default "created") --reverse Reverse the display order (default "DESC") --paginate string Paginate the result. Max 100 at a time, format: <from>:<limit> where <from> is optional (default "0:100") --plain Display output in plain mode --no-headers Don't display table headers in plain mode. Works only with --plain --no-truncate Show all available columns in plain mode. Works only with --plain --delimiter string Custom delimeter for columns in plain mode. Works only with --plain (default "\t") --comments uint Show N comments when viewing the issue (default 1) --raw Print raw JSON output --csv Print output in CSV format --columns string Comma separated list of columns to display in the plain mode. Accepts: TYPE, KEY, SUMMARY, STATUS, ASSIGNEE, REPORTER, PRIORITY, RESOLUTION, CREATED, UPDATED, LABELS --fixed-columns uint Number of fixed columns in the interactive mode (default 1) -h, --help help for list
INHERITED FLAGS -c, --config string Config file (default is /home/mslinn/.config/.jira/.config.yml, can be overridden with JIRA_CONFIG_FILE env var) --debug Turn on debug output -p, --project string Jira project to look into (defaults to /home/mslinn/.config/.jira/.config.yml)
EXAMPLES $ jira issue list
# Limit list to 20 items $ jira issue list --paginate 20
# Get 50 items starting from 10 $ jira issue list --paginate 10:50
# Search for issues containing specific text $ jira issue list "Feature Request"
# List issues in a plain table view without headers $ jira issue list --plain --no-headers
# List some columns of the issue in a plain table view $ jira issue list --plain --columns key,assignee,status
# List issues in a plain table view and show all fields $ jira issue list --plain --no-truncate
# List issues in a plain table view using custom delimiter (default is "\t") $ jira issue list --plain --delimeter "|"
# List issues as raw JSON data $ jira issue list --raw
# List issues of type "Epic" in status "Done" $ jira issue list -tEpic -sDone
# List issues in status other than "Open" and is assigned to no one $ jira issue list -s~Open -ax
# List issues from all projects $ jira issue list -q"project IS NOT EMPTY"
ALIASES lists ls search
LEARN MORE Use 'jira <command> <subcommand> --help' for more information about a command. Read the doc or get help at https://github.com/ankitpokhrel/jira-cli
Help for the jira issue view sub-subcommand:
Shell
$ jira issue view -h View displays contents of an issue.
[1mUSAGE[0m jira issue view ISSUE-KEY [flags]
[1mFLAGS[0m --comments uint Show N comments (default 1) -h, --help help for view --plain Display output in plain mode --raw Print raw Jira API response
[1mINHERITED FLAGS[0m -c, --config string Config file (default is /home/mslinn/.config/.jira/.config.yml, can be overridden with JIRA_CONFIG_FILE env var) --debug Turn on debug output -p, --project string Jira project to look into (defaults to /home/mslinn/.config/.jira/.config.yml)
[1mARGUMENTS[0m ISSUE-KEY Issue key, eg: ISSUE-1
[1mEXAMPLES[0m $ jira issue view ISSUE-1
# Show 5 recent comments when viewing the issue $ jira issue view ISSUE-1 --comments 5
# Get the raw JSON data $ jira issue view ISSUE-1 --raw
[1mALIASES[0m show
[1mLEARN MORE[0m Use 'jira <command> <subcommand> --help' for more information about a command. Read the doc or get help at https://github.com/ankitpokhrel/jira-cli
Issues Updated on a Certain Date
Shell
$ jira issue list --updated 2021-11-17
Issues Selected by Complex Criteria
The following command will yield a list of high-priority issues, created this month, with status To Do,
that are assigned to you, and have the label backend.
Shell
$ jira issue list -yHigh -s"To Do" --created month -lbackend -a$(jira me)
Output might look something like the following, which was redacted:
Issue Ids Only
The --plain and --no-headers options are useful for driving scripts.
Shell
$ jira issue list --updated 2021-11-17 --plain --no-headers --columns KEY
View Issue
The following returns the available information about an issue, in a plain-text format.
Shell
$ jira issue view ISSUE-1 --comments 9999 --plain
Verdict
JiraCLI is useful project! I reach for it any time I need to gather data about a project for a court case.
😁
