jira-commands 0.22.1

Command line utilities for interacting with JIRA

jira-commands

Table of Contents

• Scripts
• Configuration
  • Basic Authentication
  • OAuth Authentication
  • PAT authentication
• Installation
  • Run via docker / nerdctl
  • Direct pip install
  • ZSH plugin
    • zgenom
    • Antigen
    • oh-my-zsh

Some command-line tools for interacting with JIRA.

Scripts

All of these scripts support --help to get a detailed list of command line options.

Name	Description
jc	Main driver. Will run all the other commands inside a docker container for you.
jc add label / jc label add	Add a label to a ticket
jc assign subtasks / jc assign ticket subtasks	Assign a ticket to someone.
jc assign ticket / jc ticket assign	Assign a ticket to someone.
jc close subtasks / jc close ticket subtasks	Close all of a ticket's subtasks
jc close ticket / jc ticket close	Close a ticket
jc comment on subtasks / jc comment on ticket subtasks	Add identical comment to all of a ticket's subtasks
jc comment on ticket / jc ticket comment	Comment on a ticket
jc create ticket / jc ticket create	Create a ticket. You will need
jc custom field allowed values	List a custom field's allowed values since JIRA isn't forthcoming about them.
jc examine ticket / jc ticket examine	Detailed dump of a ticket and all its custom field names
jc extract customfield mappings	Extract the custom field mappings from an issue into a file
jc get label / jc list labels	List labels on a ticket
jc get link types	Prints the names of all link types defined on your JIRA instance.
jc get priority ids	Prints the names of all ticket priorities defined on your JIRA instance.
jc label remove / jc remove label	Remove a label from a ticket
jc link tickets / jc ticket link	Link two tickets. Use jc get link types to see what link names are defined on your JIRA server. Case matters.
jc list project tickets	List open tickets in a given JIRA project
jc list subtasks	Close all of a ticket's subtasks
jc list ticket transitions / jc ticket transition list	See the availale transitions for a given ticket.
jc transition ticket to / jc ticket transition set	Transition a ticket to another state. Use jc list ticket transitions to see which are available
jc vivisect ticket / jc ticket vivisect	Detailed dump of a ticket to find out all the custom field names and other innards.
jc transition subtasks / jc transition ticket subtasks	Transition all of a ticket's subtasks to a specific state

The jc program is the main driver script and will find the subcommands, so you can do jc ticket comment --ticket ABC-123 --comment 'foo bar baz' and it will find the jc-ticket-comment script and run it with the --ticket and --comment arguments.

If you're using the docker method, jc will automatically run the subcommands inside a container for you. If you've installed via pip, it'll find the commands where they were installed in your $PATH.

Configuration

The jc commands all read settings from ~/.jira-commands/jira.yaml. Settings in the file can be overridden by specifying command-line options.

Basic Authentication

I'm setting my username and jira server in the example configuraation file below. The tools will ask for my password when I run them.

jira_server: https://jira.example.com
username: YOUR_JIRA_USER

You can specify a password key but it's a terrible idea.

OAuth Authentication

Here's an example settings file for oauth authentication. Add --auth=OAUTH to use oath instead of basic authentication.

jira_server: https://jira.example.com/
oauth_access_token: ABCDabcdABCDabcdABCDabcdABCDabcd
oauth_access_token_secret: ABCDabcdABCDabcdABCDabcdABCDabcd
oauth_consumer_key: OAUTH_CONSUMER_KEY_ID
oauth_private_key_pem_pathL: /path/to/pem/file
username: YOUR_JIRA_USER

PAT authentication

Here's an example settings file for PAT authentication.

username: YOUR_JIRA_USER
pat_token: xyzzyAbc123
jira_server: https://jira.example.com/

Installation

Run via docker / nerdctl

This is the recommended way to use the jc commands, and how it will be run if you use one of the ZSH frameworks detailed below.

If you're not using a ZSH framework, clone this repository and add its bin directory to your $PATH. It contains a jc script that will detect whether you have nerdctl or docker and if it finds them, map ~/jira-commands (and the configuration file there) into a volume in the jira-commands container and run the tools inside the container.

Direct pip install

sudo pip install jira-commands will install the command-line tools via pip. This may cause compatibility annoyances with other python tools on your system, so there's a docker/nerdctl option as well.

ZSH plugin

The tooling has been packaged as a ZSH plugin to make using it as easy as possible for ZSH users.

zgenom

If you're using Zgenom:

1. Add zgenom load unixorn/jira-commands to your .zshrc with your other plugins
2. zgenom reset && zgenom save

Antigen

If you're using Antigen:

1. Add antigen bundle unixorn/jira-commands to your .zshrc where you've listed your other plugins.
2. Close and reopen your Terminal/iTerm window to refresh context and use the plugin. Alternatively, you can run antigen bundle unixorn/jira-commands in a running shell to have antigen load the new plugin.

oh-my-zsh

If you're using oh-my-zsh:

1. Clone the repository into a new jira-commands directory in oh-my-zsh's plugin folder:

   git clone https://github.com/unixorn/jira-commands.git $ZSH_CUSTOM/plugins/jira-commands

2. Edit your ~/.zshrc and add jira-commands – same as clone directory – to the list of plugins to enable:

   plugins=( ... jira-commands )

3. Then, restart your terminal application to refresh context and use the plugin. Alternatively, you can source your current shell configuration:

   source ~/.zshrc