go-jira

Simple command line client for Atlassian's Jira service written in Go.

When this tool was initial written the "username" parameter was widely used in the Atlassian API. Due to GDPR restrictions this parameter was been almost completely phased out other then V1 login. The "--user" field is still provided as a default global, however moving forward any usage of this field should be phased out in favor of the "--login" option.

Commands which previously took a username will now expect an email address such as watch, create, assign, etc...

You can download one of the pre-built binaries for go-jirahere.

You can build and install the official repository with Go (before running the below command, ensure you have GO111MODULE=on set in your environment):

This will checkout this repository into $GOPATH/src/github.com/go-jira/jira/, build, and install it.

It should then be available in $GOPATH/bin/jira.

Since go-jira is built with the "kingpin" golang command line library we support bash/zsh shell completion automatically:

https://github.com/alecthomas/kingpin/tree/v2.2.5#bashzsh-shell-completion

For example, in bash, adding something along the lines of:

eval "$(jira --completion-script-bash)"

to your bashrc, or .profile (assuming go-jira binary is already in your path) will cause jira to offer tab completion behavior.

go-jirauses a configuration hierarchy.  When loading the configuration from disk it will recursively look through all parent directories in your current path looking for a .jira.ddirectory.  If your current directory is not a child directory of your homedir, then your homedir will also be inspected for a .jira.ddirectory.  From all of .jira.ddirectories discovered go-jirawill load a <command>.ymlfile (ie for jira list it will load .jira.d/list.yml ) then it will merge in any properties from the config.ymlif found.  The configuration properties found in a file closest to your current working directory will have precedence.  Properties overridden with command line options will have final precedence.

The complicated configuration hierarchy is used because go-jiraattempts to be context aware.  For example, if you are working on a "foo" project and you cd into your project workspace, wouldn't it be nice if jira ls automatically knew to list only issues related to the "foo" project?  Likewise when you cd to the "bar" project then jira ls should only list issues related to "bar" project.  You can do this with by creating a configuration under your project workspace at ./.jira.d/config.ymlthat looks like:

You will need to specify your local jira endpoint first, typically in your homedir like:

Then use jira login to authenticate yourself as $USER. To change your username, use the -u CLI flag or set user: in your config.yml

If the .jira.d/config.ymlfile is executable, then go-jirawill attempt to execute the file and use the stdout for configuration.  You can use this to customize templates or other overrides depending on what type of operation you are running.  For example if you would like to use the "table" template when ever you run jira ls, then you can create a template like this:

Or if you always set the same overrides when you create an issue for your project you can do something like this:

You can now create custom commands for jira just by editing your .jira.d/config.yml config file.  These commands are effectively shell-scripts that can have documented options and arguments. The basic format is like:

Where the individual commands are maps with these keys:

name: string [required] This is the command name, so for jira foobar you would have name: foobar

help: string This is help message displayed in the usage for the command

hidden: bool This command will be hidden from users, but still executable.  Sometimes useful for constructing complex commands where one custom command might call another.

default: bool Use this for compound command groups.  If you wanted to have jira foo bar and jira foo baz you would have two commands with name: foo bar and name: foo baz.  Then if you wanted jira foo baz to be called by default when you type jira foo you would set default: true for that custom command.

options: list This is the list of possible option flags that the command will accept

args: list This is the list of command arguments (like the ISSUE) that the command will accept.

aliases: string list : This is a list of alternate names that the user can provide on the command line to run the same command.  Typically used to shorten the command name or provide alternatives that users might expect.

script: string [required] This is the script that will be executed as the action for this command. The value will be treated as a template and substitutions for options and arguments will be made before executing.

These are possible keys under the command options property:

name: string [required] Name of the option, so name: foobar will result in --foobar option.

help: string The help message displayed in usage for the option.

type: string :  The type of the option, can be one of these values: BOOL, COUNTER, ENUM, FLOAT32, FLOAT64, INT8, INT16, INT32, INT64, INT, STRING, STRINGMAP, UINT8, UINT16, UINT32,  UINT64 and UINT.  Most of these are primitive data types an should be self-explanatory.  The default type is STRING. There are some special types:

COUNTER will be an integer type that increments each time the option is used.  So something like --count --count will results in {{options.count}} of 2.

ENUM type is used with the enum property.  The raw type is a string and mustbe one of the values listed in the enum property.

STRINGMAP is a string => string map with the format of KEY=VALUE.  So --override foo=bar --override bin=baz will allow for {{options.override.foo}} to be bar and {{options.override.bin}} to be baz.

short: char The single character option to be used so short: c will allow for -c.

required: bool Indicate that this option must be provided on the command line.  Conflicts with the default property.

default: any Specify the default value for the option.  Conflicts with the required property.

hidden: bool Hide the option from the usage help message, but otherwise works fine.  Sometimes useful for developer options that user should not play with.

repeat: bool Indicate that this option can be repeated.  Not applicable for COUNTER and STRINGMAP types.  This will turn the option value into an array that you can iterate over.  So --day Monday --day Thursday can be used like {{range options.day}}Day: {{.}}{{end}}

enum: string list Used with the type: ENUM property, it is a list of strings values that represent the set of possible values the option accepts.

These are possible keys under the command args property:

name: string [required] Name of the option, so name: ISSUE will show in the usage as jira <command> ISSUE.  This also represents the name of the argument to be used in the script template, so {{args.ISSUE}}.

help: string The help message displayed in usage for the argument.

type: string :  The type of the argument, can be one of these values: BOOL, COUNTER, ENUM, FLOAT32, FLOAT64, INT8, INT16, INT32, INT64, INT, STRING, STRINGMAP, UINT8, UINT16, UINT32,  UINT64 and UINT.  Most of these are primitive data types an should be self-explanatory.  The default type is STRING.  There are some special types:

COUNTER will be an integer type that increments each the argument is provided  So something like jira <command> ISSUE-12 ISSUE-23 will results in {{args.ISSUE}} of 2.

ENUM type is used with the enum property.  The raw type is a string and mustbe one of the values listed in the enum property.

STRINGMAP is a string => string map with the format of KEY=VALUE.  So jira <command> foo=bar bin=baz along with a name: OVERRIDE property will allow for {{args.OVERRIDE.foo}} to be bar and {{args.OVERRIDE.bin}} to be baz.

required: bool Indicate that this argument must be provided on the command line.  Conflicts with the default property.

default: any Specify the default value for the argument.  Conflicts with the required property.

repeat: bool Indicate that this argument can be repeated.  Not applicable for COUNTER and STRINGMAP types.  This will turn the template value into an array that you can iterate over.  So jira <command> ISSUE-12 ISSUE-23 can be used like {{range args.ISSUE}}Issue: {{.}}{{end}}

enum: string list Used with the type: ENUM property, it is a list of strings values that represent the set of possible values for the argument.

The script property is a template that would produce /bin/sh compatible syntax after the template has been processed.  There are 2 key template functions {{args}} and {{options}} that return the parsed arguments and option flags as a map.

To demonstrate how you might use args and options here is a custom-test command:

Then to run it:

The script has access to all the environment variables that are in your current environment plus those that jira will set.  jira sets environment variables for each config property it has parsed from .jira.d/config.yml or the command configs at .jira.d/<command>.yml.  It might be useful to see all environment variables that jira is producing, so here is a simple custom command to list them:

You could use the environment variables automatically, so if your .jira.d/config.yml looks something like this:

jira mine for listing issues assigned to you

jira sprint for listing issues in your current sprint

When you run command like jira edit it will open up your favorite editor with the templatized output so you can quickly edit.  When the editor closes go-jirawill submit the completed form.  The order which go-jiraattempts to determine your preferred editor is:

editorproperty in any config.yml file

JIRA_EDITORenvironment variable

EDITORenvironment variable

vim

go-jirahas the ability to customize most output (and editor input) via templates.  There are default templates available for all operations, which may or may not work for your actual jira implementation.  Jira is endlessly customizable, so it is hard to provide default templates that will work for all issue types.

When running a command like jira edit it will look through the current directory hierarchy trying to find a file that matches .jira.d/templates/edit, if found it will use that file as the template, otherwise it will use the default edittemplate hard-coded into go-jira.  You can export the default hard-coded templates with jira export-templates which will write them to ~/.jira.d/templates/.

First the basic templating functionality is defined by the Go language 'text/template' library.  The library reference documentation can