| Name | jiratui JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | A TUI for interacting with Atlassian's Jira from your terminal. |
| upload_time | 2025-09-01 16:39:25 |
| maintainer | Gaston T. |
| docs_url | None |
| author | Gaston T. |
| requires_python | <3.14,>=3.10 |
| license | None |
| keywords |
tui
jira
cli
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# JiraTUI
A **Text User Interface (TUI)** for interacting with Atlassian Jira directly from your shell.
## Installation
The recommended way to install the application is via [uv](https://docs.astral.sh/uv/):
```shell
uv add jiratui
```
Alternatively, you can install it using `pip`:
```shell
pip 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.
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.
```
## Settings
Before using the application, you need to configure a few settings.
**Tip**: the application uses [Pydantic Settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/). This allows
you to define the configuration variables as ENV variables. To do that simply set the value of the config variable you
want to define in a ENV variable called `JIRA_TUI_*`; where `*` is the name of the config variable.
**Example**: to define the value of `jira_api_username` do this: `JIRA_TUI_JIRA_API_USERNAME=...`
## Setting Up the Jira's Instance API
You must provide the following values to connect to your Jira instance API:
- `jira_api_username`: the username for connecting to your Jira's API.
- `jira_api_token`: the token for connecting to your Jira's API.
- `jira_api_base_url`: the base URL of your Jira instance API.
You have a couple of options for setting these values.
### Use a `.env` File
Create a `.env` file named `.env.jiratui` and add the following content:
```yaml
JIRA_TUI_JIRA_API_USERNAME=<your-jira-api-username>
JIRA_TUI_JIRA_API_TOKEN=<your-jira-api-token>
JIRA_TUI_JIRA_API_BASE_URL=https://<your-jira-instance-hostname>.atlassian.net
```
### Use a Config File
You can also use a combination of a `.env` file and a config file. For example, keep the API username and token in the
`.env` file while placing the rest of the settings in a config file. The default config file expected by the application
is `jiratui.yaml`, but you can name your config file anything you like and specify it using the environment variable
`JIRA_TUI_CONFIG_FILE` when interacting with the CLI/app.
Example: Create a file called `my-jiratui-config.yaml` and add the following:
```yaml
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.
## 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=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" |
```
### Listing Comments
To list the comments of a work item use the `comments list` command and pass the (case-sensitive) key of the work
item whose comments you want to list.
```shell
$ jiratui comments list SCRUM-1
| ID | Issue Key | Author | Created | Updated | Message |
|----|-----------|--------------------|------------------|------------------|--------------|
| 1 | SCRUM-1 | maggie@simpson.com | 2025-12-31 16:09 | 2025-12-31 16:09 | Hello World! |
```
If you want to see the text of a specific comment use the `comments show` command and pass the (case-sensitive) key of
the work item followed by the ID of the comment.
```shell
$ jiratui comments show SCRUM-1 1
Hello World!
```
# 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).
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",
"author": "Gaston T.",
"author_email": "Gaston T. <pythondeveloper@outlook.com>",
"download_url": "https://files.pythonhosted.org/packages/84/75/4104279a92762d55fc117bcc7c4b2e3a0fa3eaba31364be9222c26078a63/jiratui-0.1.0.tar.gz",
"platform": null,
"description": "# JiraTUI\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## Installation\n\nThe recommended way to install the application is via [uv](https://docs.astral.sh/uv/):\n\n```shell\nuv add jiratui\n```\n\nAlternatively, you can install it using `pip`:\n\n```shell\npip 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 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```\n\n## Settings\n\nBefore using the application, you need to configure a few settings.\n\n**Tip**: the application uses [Pydantic Settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/). This allows\nyou to define the configuration variables as ENV variables. To do that simply set the value of the config variable you\nwant to define in a ENV variable called `JIRA_TUI_*`; where `*` is the name of the config variable.\n\n**Example**: to define the value of `jira_api_username` do this: `JIRA_TUI_JIRA_API_USERNAME=...`\n\n## Setting Up the Jira's Instance API\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's API.\n- `jira_api_token`: the token for connecting to your Jira's API.\n- `jira_api_base_url`: the base URL of your Jira instance API.\n\nYou have a couple of options for setting these values.\n\n### Use a `.env` File\n\nCreate a `.env` file named `.env.jiratui` and add the following content:\n\n```yaml\nJIRA_TUI_JIRA_API_USERNAME=<your-jira-api-username>\nJIRA_TUI_JIRA_API_TOKEN=<your-jira-api-token>\nJIRA_TUI_JIRA_API_BASE_URL=https://<your-jira-instance-hostname>.atlassian.net\n```\n\n### Use a Config File\n\nYou can also use a combination of a `.env` file and a config file. For example, keep the API username and token in the\n`.env` file while placing the rest of the settings in a config file. The default config file expected by the application\nis `jiratui.yaml`, but you can name your config file anything you like and specify it using the environment variable\n`JIRA_TUI_CONFIG_FILE` when interacting with the CLI/app.\n\nExample: Create a file called `my-jiratui-config.yaml` and add the following:\n\n```yaml\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## 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=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\n### Listing Comments\n\nTo list the comments of a work item use the `comments list` command and pass the (case-sensitive) key of the work\nitem whose comments you want to list.\n\n```shell\n$ jiratui comments list SCRUM-1\n\n| ID | Issue Key | Author | Created | Updated | Message |\n|----|-----------|--------------------|------------------|------------------|--------------|\n| 1 | SCRUM-1 | maggie@simpson.com | 2025-12-31 16:09 | 2025-12-31 16:09 | Hello World! |\n```\n\nIf you want to see the text of a specific comment use the `comments show` command and pass the (case-sensitive) key of\nthe work item followed by the ID of the comment.\n\n```shell\n$ jiratui comments show SCRUM-1 1\n\nHello World!\n```\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",
"bugtrack_url": null,
"license": null,
"summary": "A TUI for interacting with Atlassian's Jira from your terminal.",
"version": "0.1.0",
"project_urls": {
"Changelog": "https://github.com/whyisdifficult/jiratui/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/whyisdifficult/jiratui/README.md",
"Homepage": "https://github.com/whyisdifficult/jiratui",
"Issues": "https://github.com/whyisdifficult/jiratui/issues",
"Repository": "https://github.com/whyisdifficult/jiratui"
},
"split_keywords": [
"tui",
" jira",
" cli"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "62b8b21c8293fe0cdd22cf613cbe7f27f1bb73b7335a921f82719d540725e1ce",
"md5": "27e0b22b9ad69b1f1a9cde11c9feb2c0",
"sha256": "366922c125790f6280ea69e395b33c1b78a6b7ab23d0ed61170665b2d010a974"
},
"downloads": -1,
"filename": "jiratui-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "27e0b22b9ad69b1f1a9cde11c9feb2c0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14,>=3.10",
"size": 140864,
"upload_time": "2025-09-01T16:39:23",
"upload_time_iso_8601": "2025-09-01T16:39:23.473225Z",
"url": "https://files.pythonhosted.org/packages/62/b8/b21c8293fe0cdd22cf613cbe7f27f1bb73b7335a921f82719d540725e1ce/jiratui-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "84754104279a92762d55fc117bcc7c4b2e3a0fa3eaba31364be9222c26078a63",
"md5": "ab3e15a5194dee206aa29326cb2bd08f",
"sha256": "580657fcde4d8f6ec63ce6578537767416d81d6a78b1cd2023a4a43c256a42f4"
},
"downloads": -1,
"filename": "jiratui-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "ab3e15a5194dee206aa29326cb2bd08f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.14,>=3.10",
"size": 105814,
"upload_time": "2025-09-01T16:39:25",
"upload_time_iso_8601": "2025-09-01T16:39:25.290959Z",
"url": "https://files.pythonhosted.org/packages/84/75/4104279a92762d55fc117bcc7c4b2e3a0fa3eaba31364be9222c26078a63/jiratui-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-01 16:39:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "whyisdifficult",
"github_project": "jiratui",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "jiratui"
}
