README
jira-cli
A Jira command line interface (forked from https://github.com/germanrcuriel/jira-cmd )
Tested Features: (see bin/tests.sh --these all work)
- Show issues assigned to you.
- Execute custom JQL
- Create an issue
- Create an issue from a template
- Configure project specific issue transitions
- Use project specific default config files -helps other developers get up to speed faster on a project
- Create releases
- Send release reports via gmail
- Assign fix version to an issue
TODO - Untested Features:
- Use jql shortcuts
- Show sprint information
- Add an issue to a sprint
- Add multiple issues to a sprint in one command
- Use user shortcuts/aliases
Installation
Install node.js.
Then, in your shell type:
$ npm install -g jira-cli
Help
Many of the commands have "sub" helps to them so if you supply the -h with the command you will see a more complete help than what is printed by the global help below. For example:
$ jira config -h
Usage: config [options]
Options:
-h, --help output usage information
-c, --clear Clear stored configuration
-t, --template <template> Start config with this given template
-v, --verbose verbose debugging output
Config Help:
Jira URL: https://foo.atlassian.net/
Username: user (for user@foo.bar)
Password: Your password
WARNING:After three failed login attempts Atlassian forces a CAPTCHA login
WARNING: which can only be done via the browser.
```
The general help is: `jira -h`
Usage: jira.js [options] [command]
Commands:
ls [options] List my issues
start <issue> Start working on an issue.
stop <issue> Stop working on an issue.
review <issue> [assignee] Mark issue as being reviewed [by assignee(optional)].
done [options] <issue> Mark issue as finished.
invalid <issue> Mark issue as finished.
mark <issue> Mark issue as.
edit <issue> [input] edit issue.
running List issues in progress.
jql [options] [query] Run JQL query
link <from> <to> [link_value] link issues
search <term> Find issues.
assign <issue> [user] Assign an issue to <user>. Provide only issue# to assign to me
watch <issue> [user] Watch an issue to <user>. Provide only issue# to watch to me
comment <issue> [text] Comment an issue.
show [options] <issue> Show info about an issue
open <issue> Open an issue in a browser
worklog <issue> Show worklog about an issue
worklogadd [options] <issue> <timeSpent> [comment] Log work for an issue
create [options] [project[-issue]] Create an issue or a sub-task
new [options] [key] Create an issue or a sub-task
config [options] Change configuration
sprint [options] Works with sprint boards
With no arguments, displays all rapid boards
With -r argument, attempt to find a single rapid board
and display its active sprints
With both -r and -s arguments
attempt to get a single rapidboard/ sprint and show its issues. If
a single sprint board isnt found, show all matching sprint boards
fix [options] <issue> <version> Set FixVersion of an issue to <version>.
release [options] <version> Create a FixVersion/Release (see release -h for more details)
send [options] Send email report (see send -h for more details)
Options:
-h, --help output usage information
-V, --version output the version number
```
Configuration Setup (Do this first)
```
$ jira config
Jira URL: https://jira.atlassian.com/
Username: xxxxxx
Password: xxxxxx
Information stored!
```
This saves your credentials (base64 encoded), and a default working configuration file in your current working directory+ /.jira-cli
.
You can also set an environment variable called JIRA_CONFIG=/path/to/your/file/config.json
which the script will use instead of the default current diretory.
Configuration Templates
By default the script uses a default configuration that needs to be adjusted to your workflows, issue transitions, and project names. However, if another developer has preconfigured a config file you can use that file as your starting point so your configuration is all setup except for your url, username and password. Do this with the -t option.
$ jira config -t /some/network/path/my_awesome_project_setup_for_me.json
Jira URL: https://jira.atlassian.com/
Username: xxxxxx
Password: xxxxxx
Information stored!
Create a jira issue
Usage: create [options] [project[-issue]]
Options:
-h, --help output usage information
-p, --project <project> Rapid board on which project is to be created
-P, --priority <priority> priority of the issue
-T --type <type> Issue type
-s --subtask <subtask> Issue subtask
-t --title <title> Issue title
-d --description <description> Issue description
-a --assignee <assignee> Issue assignee
Using jira issue templates
What does jira new offers
- if you make issues very frequently then you can save multiple templates of default values with a key to call with in ~/jira/config.json . then you just have to do jira new KEY1 *
"default_create" : {
<!-- fields which you want to prompt every time -->
<!-- whenever you create a new issue -->
"__always_ask" :{
"fields" :{
"description" :{}, <!-- description would be prompted everytime -->
"priority": {} <!-- priority would be prompted every time -->
}
},
<!-- you will do jira new KEY1 to use this template of default values -->
"KEY1" : {
"project": "YOUR_PROJECT", <!-- mandatory -->
"issueType": 3, <!-- mandatory -->
"default" : {
"components": [{
"id": "15226"
}],
"customfield_12901" : "infrastructure",
"customfield_10008" : "MDO-9584",
"customfield_12902": {
"id": "11237"
},
<!-- in this case, this customfield corresponds to cc-->
<!-- , so when creating new jira with this template-->
<!-- every iissue would have username prakhar in cc-->
"customfield_10901": [{ <!-- how to give usernames -->
"name": "prakhar"
}]
},
"quick" : { <!-- another template shortcut -->
},
"SOME_ALIAS" :{ <!-- yet another template shortcut -->
}
},
}
- Now there are 2 portions of
default_create
config__always_ask
: it contains the fields which would always be prompted when you create an issue. For eg. in above given json , whenever we'll create a new issue , description and priority would always be asked along with other mandatory fields for the board.- Rest of the keys in
default_create
are the shortcut keys which you will refer to while calling jira new key
Edit a Jira issue:
This jira edit functionality is in beta phase and only few type of fields are allowed to be edited. currently only items of type strings are supported
- jira edit JRA-254
(0) Summary (1) Issue Type (2) Component/s (3) Dev Estimate (4) Description (5) Fix Version/s (6) Priority (7) Labels (8) Code Reviewer (9) Sprint (10) Epic Link (11) Attachment (12) Depn Team (13) CC (14) Due Date (15) Linked Issues (16) Comment (17) Assignee enter Input 7 labels Enter value testlabel1,testlabel2 Issue edited successfully!
```
to edit jira in non interactive mode, giving field to be edited and its values is possible.
- you first need to find the actual name of the field you want to edit. For this you can use the following url https://YOUR__JIRA__ENDPOINT/rest/api/2/issue/JRA-546/editmeta replace JRA-546 with the issue/type of issues you want to edit. Its sample output is given below
fields{ summary{…} issuetype{…} components{…} customfield_12000{…} description{…} fixVersions{…} priority{…} labels { requiredfalse schema{ type"array" items"string" system"labels" } name"Labels" autoCompleteUrl"https://jira.mypaytm.com….0/labels/suggest?query=" operations[…] } customfield_11600{…} customfield_10007{…} customfield_10008{…} attachment{…} customfield_11901{…} customfield_10901{…} duedate{…} issuelinks{…} comment{…} assignee{…} }
*
<kbd>jira edit JRA-254 "FIELD_NAME::FIELDVALUES"</kbd>
* Fieldnames can be hard to remember when using on command line, so you can save these field names in `~/.jira/config.json` . Suppose the response of edit meta is
``` json
fields {
summary {…}
issuetype {…}
components {…}
customfield_12000 {…}
description {…}
fixVersions {…}
priority {
required false
schema {
type "priority"
system "priority"
}
name "Priority"
operations […]
allowedValues {
0 {
self "https://jira.mypaytm.com/rest/api/2/priority/1"
iconUrl "https://jira.mypaytm.com…/priorities/critical.svg"
name "Highest"
id "1"
},
1 {
self "https://jira.mypaytm.com/rest/api/2/priority/2"
iconUrl "https://jira.mypaytm.com…cons/priorities/high.svg"
name "High"
id "2"
}
2 {,
self "https://jira.mypaytm.com/rest/api/2/priority/3"
iconUrl "https://jira.mypaytm.com…ns/priorities/medium.svg"
name "Medium"
id "3"
},
3 {
self "https://jira.mypaytm.com/rest/api/2/priority/4"
iconUrl "https://jira.mypaytm.com…icons/priorities/low.svg"
name "Low"
id "4"
},
4 {
self "https://jira.mypaytm.com/rest/api/2/priority/5"
iconUrl "https://jira.mypaytm.com…ns/priorities/lowest.svg"
name "Lowest"
id "5"
}
5 {…}
6 {…}
7 {…}
8 {…}
9 {…}
}
labels {…}
customfield_11600 {…}
customfield_10007 {…}
customfield_10008 {…}
attachment {…}
customfield_11901 {…}
customfield_10901 {…}
duedate {…}
issuelinks {…}
comment {…}
assignee {…}
}
```
* In above meta priority corresponds to CC field. So settign its default value in config.json would be
``` json
"edit_meta": {
"__default": { <!-- would work like "jira CART-2047 alias_for_high" would change the priority of task to high -->
"alias_for_high": {
"fields": {
"priority": {
"id": "2"
}
}
}
},
"sprint": {
"key": "customfield_10007"
},
"alias_for_label": { <!-- would work "jira edit CART-2047 alias_for_label::label1,label2" -->
"key": "labels",
"default": {
"test1": "t1,t2"
}
}
},
- entries in edit_meta are as follows
- __default : corresponds to raw put body we can put in config.json, which is passed as it is to the put call to jira edit api.
- Other keys at the level of __default are alias for fields which can be used as shortform for bigger named keys. Eg. jira edit JRA-546 "sprint::123" would first check alias for key sprint in
edit_meta
, if found it picks thekey
field from the alias. and makes a put call corresponding to the actual key that has been stored.- key : actual key to which call is made to edit
- default : if input value is not given corresponding to a key , for eg. jira edit JRA-354
alias_for_label
, then it picks this default key from config.json as though the input was given from commandline. It would act as if the command issued was jira edit JRA-354 "alias_for_label
::t1,t2"
- remember that enties in __default should be of form alias: {...actual json.. }
Jira mark functionality to mark a jira as done,blocked, invalid etc jira mark JRA-123
There are multiple other jira transitions beside done,invalid,start,stop etc which are directly supported as jira done JRA-123 or jira invalid JRA-786 etc.
Sometimes some jira do not change transition into these states directly due to defined workflow. They can go into certain states only from current state. In these cases or in general you can use jira mark functionality. It works as follows jira mark CART-2047