Need help with jira-cmd?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

palashkulsh
206 Stars 64 Forks MIT License 323 Commits 5 Opened issues

Description

Another JIRA Command Line Interface for node.js

Services available

!
?

Need anything else?

Contributors list

jira-cmd

NPM Version Build Status Package downloads paypal

A Jira command line interface based on jilla.

Its got tons of functionalities * showing all jira assigned to you * show all jira corresponding to custom JQL * showing all jira with shortcut to custom JQL saved in config * creating new jira * creating new jira with shortcut that picks the default values for fields configured in config * showing sprint details and sprint id for boards * adding an issue to sprint * adding multiple issues to a sprint in one go * ability to use username alias shortcuts for commenting,assigning and adding watchers. It helps to not remember the usernames, just save their shortcuts in config.

Installation

Install node.js.

Then, in your shell type:

$ npm install -g jira-cmd

Usage

First use
$ jira
Jira URL: https://jira.atlassian.com/
Username: xxxxxx
Password: xxxxxx
Information stored!

This save your credentials (base64 encoded) in your

$HOME/.jira
folder.
Help

Usage: jira.js [options] [command]

Commands:

ls [options]           List my issues
start           Start working on an issue.
stop            Stop working on an issue.
review  [assignee] Mark issue as being reviewed [by assignee(optional)].
done [options]  Mark issue as finished.
running                List issues in progress.
jql [options]   Run JQL query
link         link issues
search           Find issues.
assign  [user]  Assign an issue to . Provide only issue# to assign to me
watch  [user]   Watch an issue to . Provide only issue# to watch to me
comment  [text] Comment an issue.
show [options]  Show info about an issue
open            Open an issue in a browser
worklog         Show worklog about an issue
worklogadd [options]   [comment] Log work for an issue
create [project[-issue]] 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

Options:

-h, --help     output usage information
-V, --version  output the version number

Using Create

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 new functionality

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" : {
    
    
    "__always_ask" :{
        "fields" :{
        "description" :{}, 
        "priority": {}     
        }
    },
    
    "KEY1" : {
        "project": "YOUR_PROJECT", 
        "issueType": 3,            
        "default" : {
            "components": [{
                "id": "15226"
            }],
            "customfield_12901" : "infrastructure",
            "customfield_10008" : "MDO-9584",
            "customfield_12902": {
                "id": "11237"
            },
            
            
            
            "customfield_10901": [{ 
                "name": "prakhar"   
            }]
        },
    "quick" : { 

    },
"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

Using jira edit functionality

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 ``` json (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.

    fields{   
      summary   {…}
      issuetype {…}
      components    {…}
      customfield_12000 {…}
      description   {…}
      fixVersions   {…}
      priority  {…}
      labels {
        required    false
        schema  {
            type    "array"
            items   "string"
            system  "labels"
        }
        name    "Labels"
        autoCompleteUrl "https://jira.com….0/labels/suggest?query="
        operations  […]
      }
      customfield_11600 {…}
      customfield_10007 {…}
      customfield_10008 {…}
      attachment    {…}
      customfield_11901 {…}
      customfield_10901 {…}
      duedate   {…}
      issuelinks    {…}
      comment   {…}
      assignee  {…}
    }
    
  • jira edit JRA-254 "FIELD_NAME::FIELDVALUES"

    • 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
     fields {
        summary {…}
        issuetype   {…}
        components  {…}
        customfield_12000   {…}
        description {…}
        fixVersions {…}
        priority    {
            required    false
            schema  {
                type    "priority"
                system  "priority"
            }
            name    "Priority"
            operations  […]
            allowedValues   {
            0   {
                self    "https://jira.com/rest/api/2/priority/1"
                iconUrl "https://jira.com…/priorities/critical.svg"
                name    "Highest"
                id  "1"
                },
            1   {
                self    "https://jira.com/rest/api/2/priority/2"
                iconUrl "https://jira.com…cons/priorities/high.svg"
                name    "High"
                id  "2"
                }
            2   {,
                self    "https://jira.com/rest/api/2/priority/3"
                iconUrl "https://jira.com…ns/priorities/medium.svg"
                name    "Medium"
                id  "3"
                },
            3   {
                self    "https://jira.com/rest/api/2/priority/4"
                iconUrl "https://jira.com…icons/priorities/low.svg"
                name    "Low"
                id  "4"
                },
            4   {
                self    "https://jira.com/rest/api/2/priority/5"
                iconUrl "https://jira.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

    "edit_meta": {
        "__default": { 
            "alias_for_high": {
                "fields": {
                    "priority": {
                        "id": "2"
                    }
                }
            }
        },
        "sprint": {
            "key": "customfield_10007"
        },
        "alias_for_label": { 
            "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 `editmeta
      , if found it picks the
      key` 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

``` json
$> jira mark JRA-2047
(71) Blocked
(91) Invalid
(141) Done(No Prod Deply)
(181) Wontfix
(251) Duplicate
(291) Partner Issue
(301) Other tech team issue
(241) Reopen
Enter transition 251

```

Using Jira JQL

  • get issues for jql eg. jira jql "YOURJQLORJQLSHORTCUT" when using a particular jql frequently , you can save that jql in ~/.jira/config.json,an example jql is saved there with key reported
  • eg . jira jql reported would run the jql written against reported key [saved by default ] in ~/.jira/config.json

    Usage: jql [options] [query]
        Options:
    
    
    -h, --help           output usage information
    -c, --custom <name>  Filter by custom jql saved in jira config

Using jira sprint functionality, you can

  • get issues tagged in a sprint eg. jira sprint -r YOURRAPIDBOARD -s STRINGTOSEARCHINSPRINTNAME
  • tag an issue in a sprint eg. jira sprint -a YOURISSUEKEY -i YOURSPRINTID
  • tag multiple issues from JQL to a sprint . Eg. jira sprint -j YOURJQLORJQLSHORTCUT -i YOURSPRINTID

Usage: sprint [options]

Options:    
-h, --help                  output usage information
-r, --rapidboard      Rapidboard to show sprints for
-s, --sprint          Sprint to show the issues
-a, --add        Add project issue to sprint
-i, --sprintId    Id of the sprint
-j, --jql              Id of the sprint
  • Suppose you want to move all of your pending issues which are present in previous sprint and not marked done . Given that
    customfield_10007
    corresponds to sprint. following jira jql -c "cf[10007]=1787 and assignee=aman6.jain and status not in ('invalid','done')" gives the issues which are not done in sprint with id 1787 . now you can use this jql to mark them moved to new sprint as jira sprint -i 1890 -j "cf[10007]=1787 and assignee=aman6.jain and status not in ('invalid','done')" . And all issues would move to sprint with id 1890. ### searching issues if you want to search a text in all the issues
  • using jira search jira jql search SEARCH_TERM
  • using jira jql [recommended] jira jql "summary ~ SEARCHTERM OR description ~ SEARCHTERM"

how to use username alias/nicknames with cmd-jira

  • find users username
  • save the username alias/nickname in user_alias block of ~/.jira/config.json .

    • for eg. if username is [email protected] and you choose nickname as palash then your user_alias map would look like
        {
            "user_alias" :{
                "nickname1" : "username of user 1",
                "nickname2" : "username 2"
            }
        }
    
    • now you can use the nickname in following commands
      • to add watchers jira watch MPP-948 nickname1
      • to tag some one in comment jira comment MPP-948 "[~nickname2] you are tagged in this comment"
      • assigning an issue to someone using nickname jira assign MPP-948 nickname1 would assign MPP-948 to nickname1 user.

finding username

  • to find a user's username
    • browse to their profile on jira
    • under their avatar/photo is a field called Username
    • this is the user's username which you should use.

Explaining ~/.jira/config.json

  • auth : here the basic authentication information is stored. You would need to change it if url of your jira is changed.

    • example block
        "auth": {
            "token": "AUTO_GENERATED_TOKEN_FROM_PASSWORD",
            "url": "YOUR_JIRA_URL",
            "user": "YOUR_JIRA_EMAIL"
        }
    
    • mostly you wont need to touch this block, only when your username or password changes then you'll have to reconfigure it using jira config command.
  • custom_jql: here you will store the jql to get the type of issues you frequently want to see and monitor in single command. eg. jira jql reported would give the issues corresponding to jql saved against reported key in custom_jql by default.

    • example block
        "custom_jql": {
            "mpp": "project=MPP and status !=done",
            "reported": "reporter=currentUser() and status not in ('Done', 'Invalid')",
        },
    
    

    • now you can use this jql in multiple commands
      • listing jql issues jira jql reported
      • adding all issues in jql to a sprint id jira sprint -j reported -i SPRINT_ID
  • default_create : now this is part of the jira new functionality, in which you can configure templates in config.json, so when you create a new jira, default values are picked from templates and other required fields or fields which you have declared mandatory are prompted for your input.

  • edit_meta

  • options

    • list_issues_columns
      : definitions of the columns used in displaying the issues with
      jira ls
      or
      jira list
      . Default columns are Key, Priority, Summary and Status. Keys are the column headers. Values are object with:
      • jsPath
        the path in the JSON of an issue (returned by a call to
        rest/api/2/search?jql=assignee=currentUser()
        , example given in Using jira edit functionality)
      • defaultValue
        (optional) if the field is not present or its value is equivalent to false (zero, null or ""), the default value will be used instead
      • isDate
        (optional) mark that the value is a date and should be formatted accordingly
      • isDuration
        (optional) mark that the value is a duration (like 2h or 3d) and should be formatted accordingly
      • truncate
        (optional) length that string values should not exceed. If they do they'll be truncated.
        "list_issues_columns": {
          "Key": {
            "jsPath": "key"
          },
          "Priority": {
            "jsPath": "fields.priority.name",
            "defaultValue": ""
          },
          "Summary": {
            "jsPath": "fields.summary",
            "truncate": 50
          },
          "Status": {
            "jsPath": "fields.status.name"
          },
          "Estimate": {
            "jsPath": "fields.progress.total",
            "isDuration": true
          },
          "Logged": {
            "jsPath": "fields.progress.progress",
            "isDuration": true
          },
          "Created": {
            "jsPath": "fields.created",
            "isDate": true
          }
        }
    
    • work_hours_in_day
      : number of hours in the working days as setup in JIRA.

Each command have individual usage help (using --help or -h)

Advanced options

Checkout

~/.jira/config.json
for more options.

MIT License

Copyright (c) 2013 [email protected]

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.