Metadata-Version: 2.4
Name: python-atlassian-cli
Version: 0.1.1
Summary: A powerful CLI tool for managing Jira and Confluence
License: MIT
Project-URL: Homepage, https://github.com/hanzhichao/atlassian-cli
Project-URL: Issues, https://github.com/hanzhichao/atlassian-cli/issues
Keywords: atlassian,jira,confluence,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: atlassian-python-api>=3.41.0
Requires-Dist: click>=8.1.0
Requires-Dist: requests>=2.31.0
Requires-Dist: html2text>=2020.1.16
Requires-Dist: rich>=13.0
Requires-Dist: mistune>=3.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-mock>=3.11; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.5; extra == "dev"
Dynamic: license-file

# atlassian-cli

A powerful command-line tool for managing **Jira** and **Confluence** built on top of [`atlassian-python-api`](https://atlassian-python-api.readthedocs.io/).

![Languate - Python](https://img.shields.io/badge/language-python-blue.svg)
![PyPI - License](https://img.shields.io/pypi/l/python-atlassian-cli)
![PyPI](https://img.shields.io/pypi/v/python-atlassian-cli)
![PyPI - Downloads](https://img.shields.io/pypi/dm/python-atlassian-cli)

## Features

- 🐛 **Jira**: List, create, update, delete issues; manage projects, sprints, users
- 📄 **Confluence**: Manage spaces, pages, attachments; search with CQL
- 🔐 **Flexible auth**: Config file + environment variable support
- 🎨 **Rich output**: Pretty, table, JSON, and lines formats (using rich)
- 📝 **Markdown support**: Create pages from Markdown with code block conversion
- 💾 **File output**: Save page content to file (--output / -o)
- ☁️ **Cloud & Server**: Supports both Atlassian Cloud and self-hosted instances

## Installation

```bash
pip install python-atlassian-cli
```

## Quick Start

### 1. Configure credentials

```bash
atlassian-cli config set
```

You'll be prompted for:
- **URL**: e.g. `https://mycompany.atlassian.net`
- **Username**: your email address
- **API Token**: get one at https://id.atlassian.com/manage/api-tokens

### 2. Or use environment variables

```bash
export ATLASSIAN_URL=https://mycompany.atlassian.net
export ATLASSIAN_USERNAME=user@example.com
export ATLASSIAN_API_TOKEN=your_api_token
```

### 3. Verify connection

```bash
atlassian-cli whoami
```

---

## Jira Commands

### Issues

```bash
# List issues (all / by project / assignee / status)
atlassian-cli jira issue list
atlassian-cli jira issue list --project MYPROJ
atlassian-cli jira issue list --assignee me
atlassian-cli jira issue list --status "In Progress"
atlassian-cli jira issue list --jql "project = MYPROJ AND sprint in openSprints()"

# Different output formats
atlassian-cli jira issue list --format table
atlassian-cli jira issue list --format json

# Get a specific issue
atlassian-cli jira issue get PROJ-123
atlassian-cli jira issue get PROJ-123 --format json

# Create an issue
atlassian-cli jira issue create --project PROJ --summary "Fix login bug" --type Bug --priority High
atlassian-cli jira issue create \
  --project PROJ \
  --summary "New feature" \
  --description "Detailed description here" \
  --type Story \
  --assignee alice@example.com \
  --labels backend --labels api

# Update an issue
atlassian-cli jira issue update PROJ-123 --summary "Updated title"
atlassian-cli jira issue update PROJ-123 --priority Highest --assignee bob@example.com

# Transition an issue
atlassian-cli jira issue transition PROJ-123 "In Progress"
atlassian-cli jira issue transition PROJ-123 Done

# Add a comment
atlassian-cli jira issue comment PROJ-123 "This is fixed in v2.1.0"

# Delete an issue (with confirmation)
atlassian-cli jira issue delete PROJ-123
```

### Projects

```bash
# List all projects
atlassian-cli jira project list
atlassian-cli jira project list --format json

# Get project details
atlassian-cli jira project get MYPROJ
```

### Sprints

```bash
# List sprints for a board
atlassian-cli jira sprint list 42
atlassian-cli jira sprint list 42 --state future
atlassian-cli jira sprint list 42 --state closed
```

### Users

```bash
# Search for users
atlassian-cli jira user search "alice"
atlassian-cli jira user search "alice@example.com" --format json
```

---

## Confluence Commands

### Spaces

```bash
# List all spaces
atlassian-cli confluence space list
atlassian-cli confluence space list --limit 50

# Get space details
atlassian-cli confluence space get MYSPACE

# Create a new space
atlassian-cli confluence space create --key NEWSP --name "New Space" --description "Team workspace"
```

### Pages

```bash
# List pages in a space
atlassian-cli confluence page list MYSPACE
atlassian-cli confluence page list MYSPACE --format table
atlassian-cli confluence page list MYSPACE --format lines  # one line per page
atlassian-cli confluence page list MYSPACE --parent 12345  # child pages

# Get a page
atlassian-cli confluence page get 67890
atlassian-cli confluence page get 67890 --format json
atlassian-cli confluence page get 67890 --format html  # raw HTML body
atlassian-cli confluence page get 67890 --format markdown  # convert to Markdown
atlassian-cli confluence page get 67890 --format brief  # brief info with ancestry (default)
atlassian-cli confluence page get 67890 -o page.md  # save to file

# Create a page
atlassian-cli confluence page create --space MYSPACE --title "Meeting Notes" --html "<p>Notes here</p>"
atlassian-cli confluence page create --space MYSPACE --title "From File" --html-file content.html
atlassian-cli confluence page create --space MYSPACE --title "From Markdown" --md "# Hello"
atlassian-cli confluence page create --space MYSPACE --title "From Markdown File" --md-file readme.md
atlassian-cli confluence page create --space MYSPACE --title "Subpage" --parent 12345

# Update a page
atlassian-cli confluence page update 67890 --title "Updated Title"
atlassian-cli confluence page update 67890 --html "<p>Updated</p>"
atlassian-cli confluence page update 67890 --html-file updated.html
atlassian-cli confluence page update 67890 --minor-edit

# Move a page
atlassian-cli confluence page move 67890 --parent 99999

# Delete a page (with confirmation)
atlassian-cli confluence page delete 67890

# Search pages with CQL
atlassian-cli confluence page search "deployment guide"
atlassian-cli confluence page search "API" --space TECH
atlassian-cli confluence page search "authentication" --format table
atlassian-cli confluence page search "" --creator me --space Testing  # pages I created
atlassian-cli confluence page search "" --creator "KevinHan" --space Testing  # by user
```

### Attachments

```bash
# List attachments on a page
atlassian-cli confluence attachment list 67890

# Upload a file to a page
atlassian-cli confluence attachment upload 67890 ./diagram.png --comment "Architecture diagram"
```

---

## Configuration

Config is stored at `~/.atlassian-cli/config.json` with `600` permissions.

```json
{
  "url": "https://mycompany.atlassian.net",
  "username": "user@example.com",
  "api_token": "your_api_token",
  "cloud": true
}
```

**Environment variables** take precedence over the config file:

| Variable | Description |
|---|---|
| `ATLASSIAN_URL` | Atlassian instance URL |
| `ATLASSIAN_USERNAME` | Your email address |
| `ATLASSIAN_API_TOKEN` | Your API token |
| `ATLASSIAN_CLOUD` | `true` (Cloud) or `false` (Server) |

Show current config (token redacted):
```bash
atlassian-cli config show
```

---

## Development

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Lint
ruff check atlassian_cli/

# Format
black atlassian_cli/

# Type check
mypy atlassian_cli/
```

## Project Structure

```
atlassian-cli/
├── atlassian_cli/
│   ├── __init__.py
│   ├── main.py              # CLI entry point & top-level commands
│   ├── config.py            # Config file & env var management
│   ├── commands/
│   │   ├── jira_commands.py      # All Jira subcommands
│   │   └── confluence_commands.py # All Confluence subcommands
│   └── utils/
│       ├── client.py        # Atlassian API client factory
│       └── formatter.py     # Output formatting helpers
├── tests/
│   └── test_cli.py          # Full test suite
├── pyproject.toml
└── README.md
```

## License

MIT
