| Name | jiratui JSON |
| Version |
1.5.0
JSON |
| download |
| home_page | None |
| Summary | A TUI for interacting with Atlassian Jira from your terminal. |
| upload_time | 2025-11-01 11:57:13 |
| maintainer | Gaston T. |
| docs_url | None |
| author | Gaston T. |
| requires_python | <3.14,>=3.10 |
| license | None |
| keywords |
tui
jira
cli
terminal
shell
task-management
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# JiraTUI
[](https://github.com/whyisdifficult/jiratui/actions/workflows/github-code-scanning/codeql)
[](https://badge.fury.io/py/jiratui)
[](https://repology.org/project/jiratui/versions)
A **Text User Interface (TUI)** for interacting with Atlassian Jira directly from your shell.
## Introduction
JiraTUI is built using the [Textual](https://textual.textualize.io/) and [Rich](https://rich.readthedocs.io/en/latest/)
frameworks.
It supports the [Jira REST API v3](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/). Starting
with v1.1.0 JiraTUI supports [Jira REST API v2](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/) as
well.
## Installation
The recommended way to install the application is via [uv](https://docs.astral.sh/uv/):
```shell
uv tool install jiratui
```
Alternatively, you can install it using `pip`:
```shell
pip install jiratui
```
or `pipx`:
```shell
pipx install jiratui
```
For Arch Linux (btw) the package is available in [AUR](https://aur.archlinux.org/packages/jiratui-git)
```shell
yay -S jiratui-git
```
You can also install using homebrew
```shell
brew install jiratui
```
## Usage
After installing the package, you can run the CLI tool with the following command:
```shell
jiratui
```
This will show you the available commands for the CLI tool
```shell
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.
config Shows the location of the configuration file.
issues Use it to search, update or delete work items.
ui Launches the Jira TUI application.
users Use it to search users and user groups.
version Shows the version of the tool.
themes List the available built-in themes.
```
You can check the installed version with
```shell
jiratui version
1.0.0
```
## Settings
Before using the application you need to provide the basic configuration. All the settings can be provided in a `yaml`
file.
The application uses the [XDG specification](https://specifications.freedesktop.org/basedir-spec/latest/) 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:
```yaml
jira_api_username: 'bart@simpson.com'
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](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/#about)
and via the [Jira Data Center's API (aka. Jira on-premises)](https://developer.atlassian.com/server/jira/platform/rest/v11001/intro/#gettingstarted).
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:
```yaml
cloud: False
```
### Choosing the API version
By default, JiraTUI uses the [Jira REST API v3](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/).
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:
```yaml
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`.
## Running the Application UI
Once you have provided the necessary settings, you can run the application's UI with the following command:
```shell
jiratui ui
```
If you are using a custom config file, run:
```shell
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`
```shell
$ 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) | lisa@simpson.com | bart@simpson.com | Write 100 times "I will be a good student" |
| SCRUM-2 | Task | 2025-06-30 15:56 | To Do (10000) | homer@simpson.com | homer@simpson.com | 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`
```shell
$ 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) | lisa@simpson.com | bart@simpson.com | 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](https://jiratui.readthedocs.io/en/latest/index.html)
# Documentation
The full documentation is available at [https://jiratui.readthedocs.io](https://jiratui.readthedocs.io/en/latest/index.html)
# Contributing
If you would like to contribute to the project make sure you are familiar with the
[contribution guidelines](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md).
# Acknowledgements
This project was inspired by the work of [Textualize](https://www.textualize.io/) and their remarkable frameworks
[Textual](https://textual.textualize.io/) and [Rich](https://rich.readthedocs.io/en/latest/).
I also want to say thanks to the teams behind [Posting](https://posting.sh/),
[Lazygit](https://github.com/jesseduffield/lazygit) and [Harlequin](https://harlequin.sh/) for making these awesome
tools. These have become the must-have tools for my development workflow.
Last but not least to my colleagues [Tomasz](https://github.com/trojkat),
[Ilyes](https://github.com/ilyeshammadi) and [Giorgos](https://github.com/giorgosT) for their
support, encouragement and for reminding me how cool is to work from your terminal (something I have forgotten).
Raw data
{
"_id": null,
"home_page": null,
"name": "jiratui",
"maintainer": "Gaston T.",
"docs_url": null,
"requires_python": "<3.14,>=3.10",
"maintainer_email": "Gaston T. <pythondeveloper@outlook.com>",
"keywords": "tui, jira, cli, terminal, shell, task-management",
"author": "Gaston T.",
"author_email": "Gaston T. <pythondeveloper@outlook.com>",
"download_url": "https://files.pythonhosted.org/packages/cd/2f/0448b1786e2856f17cec35b9676805fae57b5d8f112f6d3aeddc1ee468e4/jiratui-1.5.0.tar.gz",
"platform": null,
"description": "# JiraTUI\n\n\n[](https://github.com/whyisdifficult/jiratui/actions/workflows/github-code-scanning/codeql)\n\n\n[](https://badge.fury.io/py/jiratui)\n[](https://repology.org/project/jiratui/versions)\n\n\nA **Text User Interface (TUI)** for interacting with Atlassian Jira directly from your shell.\n\n![The initial screen of JiraTUI](https://whyisdifficult.github.io/jiratui/assets/img/gallery/app-homepage.png \"JiraTUI initial screen\")\n\n## Introduction\n\nJiraTUI is built using the [Textual](https://textual.textualize.io/) and [Rich](https://rich.readthedocs.io/en/latest/)\nframeworks.\n\nIt supports the [Jira REST API v3](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/). Starting\nwith v1.1.0 JiraTUI supports [Jira REST API v2](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/) as\nwell.\n\n## Installation\n\nThe recommended way to install the application is via [uv](https://docs.astral.sh/uv/):\n\n```shell\nuv tool install jiratui\n```\n\nAlternatively, you can install it using `pip`:\n\n```shell\npip install jiratui\n```\n\nor `pipx`:\n\n```shell\npipx install jiratui\n```\n\nFor Arch Linux (btw) the package is available in [AUR](https://aur.archlinux.org/packages/jiratui-git)\n\n```shell\nyay -S jiratui-git\n```\n\nYou can also install using homebrew\n\n```shell\nbrew install jiratui\n```\n\n## Usage\n\nAfter installing the package, you can run the CLI tool with the following command:\n\n```shell\njiratui\n```\n\nThis will show you the available commands for the CLI tool\n\n```shell\nUsage: jiratui [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n --help Show this message and exit.\n\nCommands:\n comments Use it to add, list or delete comments associated to work items.\n config Shows the location of the configuration file.\n issues Use it to search, update or delete work items.\n ui Launches the Jira TUI application.\n users Use it to search users and user groups.\n version Shows the version of the tool.\n themes List the available built-in themes.\n```\n\nYou can check the installed version with\n\n```shell\njiratui version\n1.0.0\n```\n\n## Settings\n\nBefore using the application you need to provide the basic configuration. All the settings can be provided in a `yaml`\nfile.\n\nThe application uses the [XDG specification](https://specifications.freedesktop.org/basedir-spec/latest/) to locate\nconfig (and log) files. The default name of the config file is `config.yaml`. You can override the location of the\nconfig file via the env variable `JIRA_TUI_CONFIG_FILE`. The application will attempt to load the config\nfile in the following way:\n\n1. If the variable `JIRA_TUI_CONFIG_FILE` is set it will use the file specified by it.\n2. If not, if `XDG_CONFIG_HOME` is set then it will load the file `$XDG_CONFIG_HOME/jiratui/config.yaml`.\n3. If not, it will attempt to load the file from `$HOME/.config/jiratui/config.yaml`.\n\n**WARNING**: Starting with version `v1.0.0` the application no longer supports using the env variable\n`JIRA_TUI_ENV_FILE` to define the `.env` file with configuration settings. Instead, all settings must be defined in the\nconfig file as described below.\n\n### Setting API Credentials\n\nYou must provide the following values to connect to your Jira instance API:\n\n- `jira_api_username`: the username for connecting to your Jira API.\n- `jira_api_token`: the token for connecting to your Jira API. This can be your Personal Access Token (PAT).\n- `jira_api_base_url`: the base URL of your Jira instance API.\n\nExample: Assuming that your config file is located at `$XDG_CONFIG_HOME/jiratui/config.yaml` you can add the following:\n\n```yaml\njira_api_username: 'bart@simpson.com'\njira_api_token: '12345'\njira_api_base_url: 'https://<your-jira-instance-hostname>.atlassian.net'\n```\n\n**Tip**: The application provides a sample config file called `jiratui.example.yaml` that you can use to define yours.\n\n### Choosing the Jira Platform\n\nJira is available via the [Jira Cloud Platform's API](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/#about)\nand via the [Jira Data Center's API (aka. Jira on-premises)](https://developer.atlassian.com/server/jira/platform/rest/v11001/intro/#gettingstarted).\nJiraTUI can connect to both platforms, although the support for Jira Data Center's API is limited.\n\nBy default, JiraTUI tries to connect to Jira Cloud Platform's API. However, if you want to use JiraTUI with your\norganization's on-premises installation you will need to configure this via the config file. To do this simply set the\nfollowing:\n\n```yaml\ncloud: False\n```\n\n### Choosing the API version\n\nBy default, JiraTUI uses the [Jira REST API v3](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/).\nThis is good when your Jira instance runs in the cloud. However, Jira also offers an on-premises installation mode and\nin these cases the version of the API may not be v3 but v2 instead. To address this JiraTUI lets you choose which\nversion of the API you can use.\n\nTo set the version of the API update your config file to include:\n\n```yaml\njira_api_version: 2\n```\n\n**Important**: when `cloud: False` JiraTUI will use the correct version for the API and ignore the value of\n`jira_api_version`. In other words, `jira_api_version` is only applicable when `cloud: True`.\n\n## Running the Application UI\n\nOnce you have provided the necessary settings, you can run the application's UI with the following command:\n\n```shell\njiratui ui\n```\n\nIf you are using a custom config file, run:\n\n```shell\nJIRA_TUI_CONFIG_FILE=/path/to/cutom-file/my-file.yaml jiratui ui\n```\n\n## CLI Interface\n\nIn addition to the `ui` command, the CLI tool offers several commands to help you manage issues, comments, and users.\n\n### Searching for Issues\n\nTo search for work items in the project `SCRUM`, use the issues search command and pass the `--project-key` argument\nwith the (case-sensitive) project key.\n\n**Example**: searching for issues of the project `SCRUM`\n\n```shell\n$ jiratui issues search --project-key SCRUM\n\n| Key | Type | Created | Status (ID) | Reporter | Assignee | Summary |\n|---------|------|------------------|---------------|-------------------|-------------------|--------------------------------------------|\n| SCRUM-1 | Bug | 2025-07-31 15:55 | To Do (10000) | lisa@simpson.com | bart@simpson.com | Write 100 times \"I will be a good student\" |\n| SCRUM-2 | Task | 2025-06-30 15:56 | To Do (10000) | homer@simpson.com | homer@simpson.com | Eat donuts |\n```\n\nTo search for a specific work item, use the issues search command with the `--key` argument and the (case-sensitive)\nissue key.\n\n**Example**: searching for the issue with key `SCRUM-1`\n\n```shell\n$ jiratui issues search --key SCRUM-1\n\n| Key | Type | Created | Status (ID) | Reporter | Assignee | Summary |\n|---------|------|------------------|---------------|-------------------|-------------------|--------------------------------------------|\n| SCRUM-1 | Bug | 2025-07-31 15:55 | To Do (10000) | lisa@simpson.com | bart@simpson.com | Write 100 times \"I will be a good student\" |\n```\n\nThe full list of commands you can use with the CLI and additional settings is available at\n[https://jiratui.readthedocs.io](https://jiratui.readthedocs.io/en/latest/index.html)\n\n# Documentation\n\nThe full documentation is available at [https://jiratui.readthedocs.io](https://jiratui.readthedocs.io/en/latest/index.html)\n\n# Contributing\n\nIf you would like to contribute to the project make sure you are familiar with the\n[contribution guidelines](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md).\n\n# Acknowledgements\n\nThis project was inspired by the work of [Textualize](https://www.textualize.io/) and their remarkable frameworks\n[Textual](https://textual.textualize.io/) and [Rich](https://rich.readthedocs.io/en/latest/).\n\nI also want to say thanks to the teams behind [Posting](https://posting.sh/),\n[Lazygit](https://github.com/jesseduffield/lazygit) and [Harlequin](https://harlequin.sh/) for making these awesome\ntools. These have become the must-have tools for my development workflow.\n\nLast but not least to my colleagues [Tomasz](https://github.com/trojkat),\n[Ilyes](https://github.com/ilyeshammadi) and [Giorgos](https://github.com/giorgosT) for their\nsupport, encouragement and for reminding me how cool is to work from your terminal (something I have forgotten).\n",
"bugtrack_url": null,
"license": null,
"summary": "A TUI for interacting with Atlassian Jira from your terminal.",
"version": "1.5.0",
"project_urls": {
"Changelog": "https://github.com/whyisdifficult/jiratui/blob/main/CHANGELOG.md",
"Documentation": "https://jiratui.readthedocs.io/en/latest/index.html",
"Homepage": "https://jiratui.sh",
"Issues": "https://github.com/whyisdifficult/jiratui/issues",
"Repository": "https://github.com/whyisdifficult/jiratui"
},
"split_keywords": [
"tui",
" jira",
" cli",
" terminal",
" shell",
" task-management"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "117553725830fc66680e5dfee82d55f055e86a89ab6e24c9acb3a5053486fe65",
"md5": "0b472ddfd6a7b43bdec054c4f3991862",
"sha256": "ef3beb3b337ce2e760750cdc70442766a25863b0a06447b72d4bba55dbf8dd80"
},
"downloads": -1,
"filename": "jiratui-1.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0b472ddfd6a7b43bdec054c4f3991862",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14,>=3.10",
"size": 207285,
"upload_time": "2025-11-01T11:57:11",
"upload_time_iso_8601": "2025-11-01T11:57:11.664638Z",
"url": "https://files.pythonhosted.org/packages/11/75/53725830fc66680e5dfee82d55f055e86a89ab6e24c9acb3a5053486fe65/jiratui-1.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "cd2f0448b1786e2856f17cec35b9676805fae57b5d8f112f6d3aeddc1ee468e4",
"md5": "5a93549e00e8f9bca27c10f606cebba0",
"sha256": "22bd60aff242530c762c6fc2c65cef964a0607635bd6ca8eed7d5aa0c8360bb7"
},
"downloads": -1,
"filename": "jiratui-1.5.0.tar.gz",
"has_sig": false,
"md5_digest": "5a93549e00e8f9bca27c10f606cebba0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.14,>=3.10",
"size": 160132,
"upload_time": "2025-11-01T11:57:13",
"upload_time_iso_8601": "2025-11-01T11:57:13.470708Z",
"url": "https://files.pythonhosted.org/packages/cd/2f/0448b1786e2856f17cec35b9676805fae57b5d8f112f6d3aeddc1ee468e4/jiratui-1.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-01 11:57:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "whyisdifficult",
"github_project": "jiratui",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "jiratui"
}
