# Jira CLI
A command-line interface for interacting with Jira.
This project uses [UV](https://github.com/astral-sh/uv) for dependency management.
## Installation
```bash
pip install cac-jira
```
## Authentication
On first-run, you'll be prompted for a Jira API token; generate one [here](https://id.atlassian.com/manage-profile/security/api-tokens). This will be stored in your system credential store (e.g. Keychain on Mac OS) in an items called `cac-jira`.
## Configuration
On first-run, a configuration file will be generated at `~/.config/cac_jira/config.yaml`. In this file you'll need to replace the values of `server` and `username` with appropriate values.
```yaml
server: https://your-jira-instance.atlassian.net
project: YOUR_PROJECT_KEY # Optional default project
username: your.email@example.com
```
## Usage
The Jira CLI follows a command-action pattern for all operations:
```bash
jira <command> <action> [options]
```
### Global Options
- `--verbose`: Enable debug output
- `--output [table|json]`: Control output format (default table)
- `--help`: Show command help
<!-- --suppress-output: Hide command output -->
<!-- --version: Display version information -->
### Examples
#### Issue Commands
List issues in a project:
```bash
jira issue list --project PROJ
```
List issues with additional filtering:
```bash
jira issue list --project PROJ
```
Create a new issue:
```bash
jira issue create --project PROJ --type Task --title "Fix login bug" --description "Users can't log in"
```
Create a new issue of a type that requires custom fields:
```bash
#
# This assumes the name of the custom fields is "Custom Field One" and "Custom Field Two";
# the field name will be swapped to lower-case, and spaces replaced with underscores
#
jira issue create --project PROJ --type Custom\ Issue\ Type --title "Issue Title" --description "Issue description" \
--field custom_field_one custom_field_value \
--field custom_field_two custom_field_value
```
Create and assign to yourself:
```bash
jira issue create --project PROJ --type Bug --title "Server crash" --assign
```
Create and immediately start work:
```bash
jira issue create --project PROJ --type Story --title "Add login feature" --begin
```
Add an issue to an epic:
```bash
jira issue create --project PROJ --type Task --title "Subtask" --epic PROJ-100
```
Label an issue:
```bash
jira issue label --issue ISSUE_KEY --labels label1,label2
```
Transition an issue:
```bash
jira issue begin --issue ISSUE_KEY # Start work
jira issue close --issue ISSUE_KEY # Mark as complete
```
#### Project Commands
List all projects:
```bash
jira project list
```
Show a project:
```bash
jira project show --name PROJ-123
```
#### Advanced Examples
Update an issue's title or description:
```bash
jira issue update --issue ISSUE_KEY --title "New issue title" --description "new issue description"
```
Add a comment to an issue:
```bash
jira issue comment --issue ISSUE_KEY --comment "This is a comment."
```
List all issue IDs matching a label:
```bash
jira issue list --output json | jq -r '.[] | select(.Labels | contains("production")) | .ID'
```
## Development
### Setup Development Environment
```bash
# Install dependencies including dev dependencies
uv sync
# Activate the venv
source .venv/bin/activate
# Run tests
uv run pytest
```
Please note that tests are still WIP
### Project Structure
- `cac_jira/commands/` - Command implementations
- `issue/` - Issue-related commands
- `project/` - Project-related commands
- `cac_jira/cli/` - CLI entry point and argument parsing
### Adding New Commands
1. Create a new action module in the appropriate command directory.
2. Define a class that inherits from the command's base class.
3. Implement `define_arguments()` and `execute()` methods.
Raw data
{
"_id": null,
"home_page": null,
"name": "cac-jira",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "jira, cli, atlassian, project-management, command-lint, python, cli-tool",
"author": null,
"author_email": "Ryan Punt <ryan@mirum.org>",
"download_url": "https://files.pythonhosted.org/packages/26/0c/930d7aeff365914e63cab443ee6d14ef73eaec9db641aaf285ebc182c1e5/cac_jira-0.5.3.tar.gz",
"platform": null,
"description": "# Jira CLI\n\nA command-line interface for interacting with Jira.\n\nThis project uses [UV](https://github.com/astral-sh/uv) for dependency management.\n\n## Installation\n\n```bash\npip install cac-jira\n```\n\n## Authentication\n\nOn first-run, you'll be prompted for a Jira API token; generate one [here](https://id.atlassian.com/manage-profile/security/api-tokens). This will be stored in your system credential store (e.g. Keychain on Mac OS) in an items called `cac-jira`.\n\n## Configuration\n\nOn first-run, a configuration file will be generated at `~/.config/cac_jira/config.yaml`. In this file you'll need to replace the values of `server` and `username` with appropriate values.\n\n```yaml\nserver: https://your-jira-instance.atlassian.net\nproject: YOUR_PROJECT_KEY # Optional default project\nusername: your.email@example.com\n```\n\n## Usage\n\nThe Jira CLI follows a command-action pattern for all operations:\n\n```bash\njira <command> <action> [options]\n```\n\n### Global Options\n\n- `--verbose`: Enable debug output\n- `--output [table|json]`: Control output format (default table)\n- `--help`: Show command help\n<!-- --suppress-output: Hide command output -->\n<!-- --version: Display version information -->\n\n### Examples\n\n#### Issue Commands\n\nList issues in a project:\n\n```bash\njira issue list --project PROJ\n```\n\nList issues with additional filtering:\n\n```bash\njira issue list --project PROJ\n```\n\nCreate a new issue:\n\n```bash\njira issue create --project PROJ --type Task --title \"Fix login bug\" --description \"Users can't log in\"\n```\n\nCreate a new issue of a type that requires custom fields:\n\n```bash\n#\n# This assumes the name of the custom fields is \"Custom Field One\" and \"Custom Field Two\";\n# the field name will be swapped to lower-case, and spaces replaced with underscores\n#\njira issue create --project PROJ --type Custom\\ Issue\\ Type --title \"Issue Title\" --description \"Issue description\" \\\n --field custom_field_one custom_field_value \\\n --field custom_field_two custom_field_value\n```\n\nCreate and assign to yourself:\n\n```bash\njira issue create --project PROJ --type Bug --title \"Server crash\" --assign\n```\n\nCreate and immediately start work:\n\n```bash\njira issue create --project PROJ --type Story --title \"Add login feature\" --begin\n```\n\nAdd an issue to an epic:\n\n```bash\njira issue create --project PROJ --type Task --title \"Subtask\" --epic PROJ-100\n```\n\nLabel an issue:\n\n```bash\njira issue label --issue ISSUE_KEY --labels label1,label2\n```\n\nTransition an issue:\n\n```bash\njira issue begin --issue ISSUE_KEY # Start work\njira issue close --issue ISSUE_KEY # Mark as complete\n```\n\n#### Project Commands\n\nList all projects:\n\n```bash\njira project list\n```\n\nShow a project:\n\n```bash\njira project show --name PROJ-123\n```\n\n#### Advanced Examples\n\nUpdate an issue's title or description:\n\n```bash\njira issue update --issue ISSUE_KEY --title \"New issue title\" --description \"new issue description\"\n```\n\nAdd a comment to an issue:\n\n```bash\njira issue comment --issue ISSUE_KEY --comment \"This is a comment.\"\n```\n\nList all issue IDs matching a label:\n\n```bash\njira issue list --output json | jq -r '.[] | select(.Labels | contains(\"production\")) | .ID'\n```\n\n## Development\n\n### Setup Development Environment\n\n```bash\n# Install dependencies including dev dependencies\nuv sync\n\n# Activate the venv\nsource .venv/bin/activate\n\n# Run tests\nuv run pytest\n```\n\nPlease note that tests are still WIP\n\n### Project Structure\n\n- `cac_jira/commands/` - Command implementations\n - `issue/` - Issue-related commands\n - `project/` - Project-related commands\n- `cac_jira/cli/` - CLI entry point and argument parsing\n\n### Adding New Commands\n\n1. Create a new action module in the appropriate command directory.\n2. Define a class that inherits from the command's base class.\n3. Implement `define_arguments()` and `execute()` methods.\n",
"bugtrack_url": null,
"license": null,
"summary": "A command-line interface for interacting with Jira",
"version": "0.5.3",
"project_urls": {
"homepage": "https://mirum.org/cac-jira/",
"repository": "https://github.com/rpunt/cac-jira"
},
"split_keywords": [
"jira",
" cli",
" atlassian",
" project-management",
" command-lint",
" python",
" cli-tool"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0d83330b4c01b61ebc991a7457882d9d049de2c5882156dce53bf316ccca3dcc",
"md5": "c2b6b841c029244fdddd71865de0a75b",
"sha256": "0ac1e3cf2d15c8418f8eaf0189dead528a33cf604ead63c692cf49df8df0f9cd"
},
"downloads": -1,
"filename": "cac_jira-0.5.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c2b6b841c029244fdddd71865de0a75b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 28772,
"upload_time": "2025-07-17T16:21:25",
"upload_time_iso_8601": "2025-07-17T16:21:25.631621Z",
"url": "https://files.pythonhosted.org/packages/0d/83/330b4c01b61ebc991a7457882d9d049de2c5882156dce53bf316ccca3dcc/cac_jira-0.5.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "260c930d7aeff365914e63cab443ee6d14ef73eaec9db641aaf285ebc182c1e5",
"md5": "f5e18dce869b80e1efd2f50249ac1c77",
"sha256": "10e0008e70ff4c8f3ecbb9326d68284e4e0833ec15cfa1c027699b22a3867dcd"
},
"downloads": -1,
"filename": "cac_jira-0.5.3.tar.gz",
"has_sig": false,
"md5_digest": "f5e18dce869b80e1efd2f50249ac1c77",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 20485,
"upload_time": "2025-07-17T16:21:27",
"upload_time_iso_8601": "2025-07-17T16:21:27.185060Z",
"url": "https://files.pythonhosted.org/packages/26/0c/930d7aeff365914e63cab443ee6d14ef73eaec9db641aaf285ebc182c1e5/cac_jira-0.5.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-17 16:21:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rpunt",
"github_project": "cac-jira",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "cac-jira"
}
JSON
