jiratui

JiraTUI

A Text User Interface (TUI) for interacting with Atlassian’s Jira directly from your shell.

Introduction

JiraTUI is built using the Textual and Rich frameworks.

JiraTUI can connect to a cloud-based Jira installation as well as to an on-premises (aka. DC) instance. It supports the Jira Cloud Platform REST API v3. Starting with v1.1.0 JiraTUI supports Jira Cloud Platform REST API v2 as well.

Installation

The recommended way to install the application is via uv:

uv tool install jiratui

Alternatively, you can install it using pip:

pip install jiratui

or pipx:

pipx install jiratui

For Arch Linux (btw) the package is available in AUR

yay -S jiratui-git

You can also install using homebrew

brew install jiratui

Usage

After installing the package, you can run the CLI tool with the following command:

jiratui

This will show you the available commands for the CLI tool

Usage: jiratui [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  comments    Use it to add, list or delete comments associated to work items.
  completions Generate shell completion script.
  config      Shows the location of the configuration file.
  configure   Use it to manage the configuration file.
  issues      Use it to create, search, update or delete work items.
  projects    Use it to manage information related to projects.
  themes      List the available built-in themes.
  ui          Launches the Jira TUI application.
  users       Use it to search users and user groups.
  version     Shows the version of the tool.

You can check the installed version with

jiratui version
1.13.0

Settings

Before using the application you need to provide the basic configuration. All the settings can be provided in a yaml file. For this you have 2 options.

• Using the CLI command jiratui configure create to launch an app that will guide through the process of generating a configuration file with the minimal settings you need for a first launch. This is only supported in JiraTUI >= v1.13.0.
• Authoring the config file manually.

Using the Configuration Manager

Simply run the following command to start up the configuration manager app.

jiratui configure create

You can pass an optional parameter -o (--output-file) with the location where you want to save the configuration file. If you do not provide this parameter the application wil save the resulting file in the standard location. See below for details.

jiratui configure create -o /Users/Downloads/file.yaml

The application launches and guides you through the process.

Authoring the Config File Manually

The application uses the XDG specification to locate config (and log) files. The default name of the config file is config.yaml. You can override the location of the config file via the env variable JIRA_TUI_CONFIG_FILE. The application will attempt to load the config file in the following way:

1. If the variable JIRA_TUI_CONFIG_FILE is set it will use the file specified by it.
2. If not, if XDG_CONFIG_HOME is set then it will load the file $XDG_CONFIG_HOME/jiratui/config.yaml.
3. If not, it will attempt to load the file from $HOME/.config/jiratui/config.yaml.

WARNING: Starting with version v1.0.0 the application no longer supports using the env variable JIRA_TUI_ENV_FILE to define the .env file with configuration settings. Instead, all settings must be defined in the config file as described below.

Setting API Credentials

You must provide the following values to connect to your Jira instance API:

• jira_api_username: the username for connecting to your Jira API.
• jira_api_token: the token for connecting to your Jira API. This can be your Personal Access Token (PAT).
• jira_api_base_url: the base URL of your Jira instance API.

Example: Assuming that your config file is located at $XDG_CONFIG_HOME/jiratui/config.yaml you can add the following:

jira_api_username: '[email protected]'
jira_api_token: '12345'
jira_api_base_url: 'https://<your-jira-instance-hostname>.atlassian.net'

Tip: The application provides a sample config file called jiratui.example.yaml that you can use to define yours.

Choosing the Jira Platform

Jira is available via the Jira Cloud Platform’s API and via the Jira Data Center’s API (aka. Jira on-premises). JiraTUI can connect to both platforms, although the support for Jira Data Center’s API is limited.

By default, JiraTUI tries to connect to Jira Cloud Platform’s API. However, if you want to use JiraTUI with your organization’s on-premises installation you will need to configure this via the config file. To do this simply set the following:

cloud: False

Choosing the API Version

By default, JiraTUI uses the Jira REST API v3. This is good when your Jira instance runs in the cloud. However, Jira also offers an on-premises installation mode and in these cases the version of the API may not be v3 but v2 instead. To address this JiraTUI lets you choose which version of the API you can use.

To set the version of the API update your config file to include:

jira_api_version: 2

Important: when cloud: False JiraTUI will use the correct version for the API and ignore the value of jira_api_version. In other words, jira_api_version is only applicable when cloud: True.

Setting Up Permissions and Scopes for your User

JiraTUI requires that your Jira user account has specific permissions configured before you can use the tool. These permissions (called “scopes” in Jira) are not set by JiraTUI. Instead, your organization’s Jira administrator must grant them to your user account.

To find out what are the minimal set of permissions your user needs to use JiraTUI refer to Permissions and Scopes.

Choosing the Keybindings Style

Starting with version 1.13.0 you can choose which style of keybindings to use. The tool offers 2 options: legacy (default) or standard. The legacy style is the original and only keybinding set offered by the tool up to version 1.12.0. The new standard keybinding set follows more standard keybindings for typical actions in a terminal.

You can choose the standard style by setting the variable key_bindings_style in the config file.

key_bindings_style: 'standard'

Running the Application UI

Once you have provided the necessary settings, you can run the application’s UI with the following command:

jiratui ui

If you are using a custom config file, run:

JIRA_TUI_CONFIG_FILE=/path/to/cutom-file/my-file.yaml jiratui ui

CLI Interface

In addition to the ui command, the CLI tool offers several commands to help you manage issues, comments, and users.

Searching for Issues

To search for work items in the project SCRUM, use the issues search command and pass the --project-key argument with the (case-sensitive) project key.

Example: searching for issues of the project SCRUM

$ jiratui issues search --project-key SCRUM

| Key     | Type | Created          | Status (ID)   | Reporter          | Assignee          | Summary                                    |
|---------|------|------------------|---------------|-------------------|-------------------|--------------------------------------------|
| SCRUM-1 | Bug  | 2025-07-31 15:55 | To Do (10000) | [email protected]  | [email protected]  | Write 100 times "I will be a good student" |
| SCRUM-2 | Task | 2025-06-30 15:56 | To Do (10000) | [email protected] | [email protected] | Eat donuts                                 |

To search for a specific work item, use the issues search command with the --key argument and the (case-sensitive) issue key.

Example: searching for the issue with key SCRUM-1

$ jiratui issues search --key SCRUM-1

| Key     | Type | Created          | Status (ID)   | Reporter          | Assignee          | Summary                                    |
|---------|------|------------------|---------------|-------------------|-------------------|--------------------------------------------|
| SCRUM-1 | Bug  | 2025-07-31 15:55 | To Do (10000) | [email protected]  | [email protected]  | Write 100 times "I will be a good student" |

The full list of commands you can use with the CLI and additional settings is available at https://jiratui.readthedocs.io

Documentation

The full documentation is available at https://jiratui.readthedocs.io

Contributing

If you would like to contribute to the project make sure you are familiar with the contribution guidelines and the Code of Conduct.

Acknowledgements

This project was inspired by the work of Textualize and their remarkable frameworks Textual and Rich.

I also want to say thanks to the teams behind Posting, Lazygit and Harlequin for making these awesome tools. These have become the must-have tools for my development workflow.

Last but not least to my colleagues Tomasz, Ilyes and Giorgos for their support, encouragement and for reminding me how cool is to work from your terminal (something I had forgotten).