atlassian-cli 0.3.0__tar.gz

atlassian_cli-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Catapult CX
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

atlassian_cli-0.3.0/PKG-INFO

@@ -0,0 +1,235 @@
+Metadata-Version: 2.4
+Name: atlassian-cli
+Version: 0.3.0
+Summary: Fast CLI tools for Atlassian Cloud (Confluence + Jira) — optimized for AI agents
+Author-email: Alex Fishlock <alex.fishlock@catapult.cx>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/catapultcx/atlassian-cli
+Project-URL: Repository, https://github.com/catapultcx/atlassian-cli
+Project-URL: Issues, https://github.com/catapultcx/atlassian-cli/issues
+Keywords: atlassian,confluence,jira,cli,claude,ai
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: responses>=0.23.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <h1 align="center">atlassian-cli</h1>
+  <p align="center">
+    Fast CLI tools for Atlassian Cloud — built for AI agents, loved by humans.
+  </p>
+</p>
+
+<p align="center">
+  <a href="https://github.com/catapultcx/atlassian-cli/actions/workflows/ci.yml"><img src="https://github.com/catapultcx/atlassian-cli/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://pypi.org/project/atlassian-cli/"><img src="https://img.shields.io/pypi/v/atlassian-cli" alt="PyPI"></a>
+  <a href="https://pypi.org/project/atlassian-cli/"><img src="https://img.shields.io/pypi/pyversions/atlassian-cli" alt="Python"></a>
+  <a href="https://github.com/catapultcx/atlassian-cli/blob/main/LICENSE"><img src="https://img.shields.io/github/license/catapultcx/atlassian-cli" alt="License"></a>
+</p>
+
+---
+
+Two CLI tools — `confluence` and `jira` — that talk directly to Atlassian Cloud REST APIs. Zero bloat, one dependency (`requests`), deterministic output that AI agents parse in a single shot.
+
+## Install
+
+```bash
+pip install atlassian-cli
+```
+
+Or from source:
+
+```bash
+pip install git+https://github.com/catapultcx/atlassian-cli.git
+```
+
+## Setup
+
+Create a `.env` file (or export environment variables):
+
+```bash
+ATLASSIAN_URL=https://your-site.atlassian.net
+ATLASSIAN_EMAIL=you@example.com
+ATLASSIAN_TOKEN=your-api-token
+```
+
+Get your API token at https://id.atlassian.com/manage-profile/security/api-tokens
+
+> Legacy `CONFLUENCE_URL` / `CONFLUENCE_EMAIL` / `CONFLUENCE_TOKEN` env vars are also supported.
+
+## Confluence CLI
+
+Manages Confluence pages as local JSON files in ADF (Atlassian Document Format). No markdown — ADF preserves every macro, panel, and table perfectly.
+
+```bash
+# Download a page
+confluence get 9268920323
+
+# Upload local edits back
+confluence put 9268920323
+confluence put 9268920323 --force          # skip version check
+
+# Compare local vs remote
+confluence diff 9268920323
+
+# Bulk-download an entire space (parallel, version-cached)
+confluence sync POL
+confluence sync COMPLY --workers 20 --force
+
+# Search local page index (instant, no API call)
+confluence search "risk assessment"
+
+# Rebuild the page index
+confluence index
+confluence index --space POL --space COMPLY
+```
+
+### How sync works
+
+`sync` downloads every page in a space using parallel workers. It caches version numbers locally — subsequent syncs only fetch pages that changed. A full space of 500+ pages takes seconds.
+
+```
+pages/
+  POL/
+    9268920323.json          # ADF body
+    9268920323.meta.json     # title, version, timestamps
+  COMPLY/
+    5227515611.json
+    5227515611.meta.json
+page-index.json              # searchable index
+```
+
+## Jira CLI
+
+### Issues
+
+Full CRUD on Jira issues via REST API v3.
+
+```bash
+# Get issue details
+jira issue get ISMS-42
+
+# Create issues
+jira issue create PROJ Task "Fix the login bug"
+jira issue create PROJ Story "User auth" --description "As a user..." --labels security urgent
+jira issue create PROJ Sub-task "Write tests" --parent PROJ-100
+
+# Update fields
+jira issue update ISMS-42 --summary "New title"
+jira issue update ISMS-42 --labels risk compliance
+jira issue update ISMS-42 --fields '{"priority": {"name": "High"}}'
+
+# Delete
+jira issue delete ISMS-42
+
+# Search with JQL
+jira issue search "project = ISMS AND status = Open"
+jira issue search "assignee = currentUser() ORDER BY updated DESC" --max 20
+
+# Transitions
+jira issue transition ISMS-42 "In Progress"
+jira issue transition ISMS-42 Done
+
+# Comments
+jira issue comment ISMS-42 "Fixed in v2.1"
+jira issue comments ISMS-42
+```
+
+### Assets (JSM)
+
+CRUD for Jira Service Management Assets via the Assets REST API v1.
+
+```bash
+# Browse schemas and types
+jira assets schemas
+jira assets schema 1
+jira assets types 1
+jira assets type 5
+jira assets attrs 5
+
+# Search with AQL
+jira assets search "objectType = Server"
+
+# CRUD objects
+jira assets get 123
+jira assets create 5 Name=srv01 IP=10.0.0.1
+jira assets update 123 Name=srv02
+jira assets delete 123
+
+# Create new object types
+jira assets type-create 1 "Network Device" --description "Switches and routers"
+```
+
+## `--json` flag
+
+Both CLIs accept a global `--json` flag that switches all output to machine-readable JSON. Perfect for piping into `jq` or parsing from code.
+
+```bash
+# Text mode (default)
+$ confluence get 9268920323
+OK Artificial Intelligence Policy (v12) -> pages/POL/9268920323.json
+
+# JSON mode
+$ confluence --json get 9268920323
+{"status":"ok","message":"Artificial Intelligence Policy (v12) -> pages/POL/9268920323.json"}
+```
+
+## Output format
+
+All commands emit status-prefixed lines for easy parsing:
+
+| Prefix | Meaning |
+|--------|---------|
+| `OK`   | Success |
+| `GET`  | Page downloaded |
+| `SKIP` | Already up-to-date |
+| `ERR`  | Error |
+| `DONE` | Batch complete |
+
+## Architecture
+
+```
+src/atlassian_cli/
+  config.py       Shared auth, .env parsing, session factory
+  http.py         API helpers: get/post/put/delete + error handling
+  output.py       Text & JSON output formatting
+  conflu.py       Confluence CLI (v2 API, ADF)
+  jira.py         Jira CLI entry point (subparsers)
+  jira_issues.py  Jira issue commands (v3 API)
+  jira_assets.py  Jira Assets commands (Assets v1 API)
+```
+
+**APIs used:**
+- Confluence Cloud REST API v2 (`/wiki/api/v2/`)
+- Jira Cloud REST API v3 (`/rest/api/3/`)
+- Jira Assets REST API v1 (`api.atlassian.com/jsm/assets/workspace/{id}/v1`)
+
+## Development
+
+```bash
+git clone https://github.com/catapultcx/atlassian-cli.git
+cd atlassian-cli
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+ruff check src/ tests/
+```
+
+## License
+
+MIT

atlassian_cli-0.3.0/README.md

@@ -0,0 +1,205 @@
+<p align="center">
+  <h1 align="center">atlassian-cli</h1>
+  <p align="center">
+    Fast CLI tools for Atlassian Cloud — built for AI agents, loved by humans.
+  </p>
+</p>
+
+<p align="center">
+  <a href="https://github.com/catapultcx/atlassian-cli/actions/workflows/ci.yml"><img src="https://github.com/catapultcx/atlassian-cli/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://pypi.org/project/atlassian-cli/"><img src="https://img.shields.io/pypi/v/atlassian-cli" alt="PyPI"></a>
+  <a href="https://pypi.org/project/atlassian-cli/"><img src="https://img.shields.io/pypi/pyversions/atlassian-cli" alt="Python"></a>
+  <a href="https://github.com/catapultcx/atlassian-cli/blob/main/LICENSE"><img src="https://img.shields.io/github/license/catapultcx/atlassian-cli" alt="License"></a>
+</p>
+
+---
+
+Two CLI tools — `confluence` and `jira` — that talk directly to Atlassian Cloud REST APIs. Zero bloat, one dependency (`requests`), deterministic output that AI agents parse in a single shot.
+
+## Install
+
+```bash
+pip install atlassian-cli
+```
+
+Or from source:
+
+```bash
+pip install git+https://github.com/catapultcx/atlassian-cli.git
+```
+
+## Setup
+
+Create a `.env` file (or export environment variables):
+
+```bash
+ATLASSIAN_URL=https://your-site.atlassian.net
+ATLASSIAN_EMAIL=you@example.com
+ATLASSIAN_TOKEN=your-api-token
+```
+
+Get your API token at https://id.atlassian.com/manage-profile/security/api-tokens
+
+> Legacy `CONFLUENCE_URL` / `CONFLUENCE_EMAIL` / `CONFLUENCE_TOKEN` env vars are also supported.
+
+## Confluence CLI
+
+Manages Confluence pages as local JSON files in ADF (Atlassian Document Format). No markdown — ADF preserves every macro, panel, and table perfectly.
+
+```bash
+# Download a page
+confluence get 9268920323
+
+# Upload local edits back
+confluence put 9268920323
+confluence put 9268920323 --force          # skip version check
+
+# Compare local vs remote
+confluence diff 9268920323
+
+# Bulk-download an entire space (parallel, version-cached)
+confluence sync POL
+confluence sync COMPLY --workers 20 --force
+
+# Search local page index (instant, no API call)
+confluence search "risk assessment"
+
+# Rebuild the page index
+confluence index
+confluence index --space POL --space COMPLY
+```
+
+### How sync works
+
+`sync` downloads every page in a space using parallel workers. It caches version numbers locally — subsequent syncs only fetch pages that changed. A full space of 500+ pages takes seconds.
+
+```
+pages/
+  POL/
+    9268920323.json          # ADF body
+    9268920323.meta.json     # title, version, timestamps
+  COMPLY/
+    5227515611.json
+    5227515611.meta.json
+page-index.json              # searchable index
+```
+
+## Jira CLI
+
+### Issues
+
+Full CRUD on Jira issues via REST API v3.
+
+```bash
+# Get issue details
+jira issue get ISMS-42
+
+# Create issues
+jira issue create PROJ Task "Fix the login bug"
+jira issue create PROJ Story "User auth" --description "As a user..." --labels security urgent
+jira issue create PROJ Sub-task "Write tests" --parent PROJ-100
+
+# Update fields
+jira issue update ISMS-42 --summary "New title"
+jira issue update ISMS-42 --labels risk compliance
+jira issue update ISMS-42 --fields '{"priority": {"name": "High"}}'
+
+# Delete
+jira issue delete ISMS-42
+
+# Search with JQL
+jira issue search "project = ISMS AND status = Open"
+jira issue search "assignee = currentUser() ORDER BY updated DESC" --max 20
+
+# Transitions
+jira issue transition ISMS-42 "In Progress"
+jira issue transition ISMS-42 Done
+
+# Comments
+jira issue comment ISMS-42 "Fixed in v2.1"
+jira issue comments ISMS-42
+```
+
+### Assets (JSM)
+
+CRUD for Jira Service Management Assets via the Assets REST API v1.
+
+```bash
+# Browse schemas and types
+jira assets schemas
+jira assets schema 1
+jira assets types 1
+jira assets type 5
+jira assets attrs 5
+
+# Search with AQL
+jira assets search "objectType = Server"
+
+# CRUD objects
+jira assets get 123
+jira assets create 5 Name=srv01 IP=10.0.0.1
+jira assets update 123 Name=srv02
+jira assets delete 123
+
+# Create new object types
+jira assets type-create 1 "Network Device" --description "Switches and routers"
+```
+
+## `--json` flag
+
+Both CLIs accept a global `--json` flag that switches all output to machine-readable JSON. Perfect for piping into `jq` or parsing from code.
+
+```bash
+# Text mode (default)
+$ confluence get 9268920323
+OK Artificial Intelligence Policy (v12) -> pages/POL/9268920323.json
+
+# JSON mode
+$ confluence --json get 9268920323
+{"status":"ok","message":"Artificial Intelligence Policy (v12) -> pages/POL/9268920323.json"}
+```
+
+## Output format
+
+All commands emit status-prefixed lines for easy parsing:
+
+| Prefix | Meaning |
+|--------|---------|
+| `OK`   | Success |
+| `GET`  | Page downloaded |
+| `SKIP` | Already up-to-date |
+| `ERR`  | Error |
+| `DONE` | Batch complete |
+
+## Architecture
+
+```
+src/atlassian_cli/
+  config.py       Shared auth, .env parsing, session factory
+  http.py         API helpers: get/post/put/delete + error handling
+  output.py       Text & JSON output formatting
+  conflu.py       Confluence CLI (v2 API, ADF)
+  jira.py         Jira CLI entry point (subparsers)
+  jira_issues.py  Jira issue commands (v3 API)
+  jira_assets.py  Jira Assets commands (Assets v1 API)
+```
+
+**APIs used:**
+- Confluence Cloud REST API v2 (`/wiki/api/v2/`)
+- Jira Cloud REST API v3 (`/rest/api/3/`)
+- Jira Assets REST API v1 (`api.atlassian.com/jsm/assets/workspace/{id}/v1`)
+
+## Development
+
+```bash
+git clone https://github.com/catapultcx/atlassian-cli.git
+cd atlassian-cli
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+ruff check src/ tests/
+```
+
+## License
+
+MIT

atlassian_cli-0.3.0/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "atlassian-cli"
+version = "0.3.0"
+description = "Fast CLI tools for Atlassian Cloud (Confluence + Jira) — optimized for AI agents"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    {name = "Alex Fishlock", email = "alex.fishlock@catapult.cx"},
+]
+keywords = ["atlassian", "confluence", "jira", "cli", "claude", "ai"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "requests>=2.28.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "responses>=0.23.0",
+    "ruff>=0.4.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/catapultcx/atlassian-cli"
+Repository = "https://github.com/catapultcx/atlassian-cli"
+Issues = "https://github.com/catapultcx/atlassian-cli/issues"
+
+[project.scripts]
+confluence = "atlassian_cli.conflu:main"
+jira = "atlassian_cli.jira:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]

atlassian_cli-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

atlassian_cli-0.3.0/src/atlassian_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Atlassian Cloud CLI tools for Confluence and Jira."""
+
+__version__ = '0.3.0'

atlassian_cli-0.3.0/src/atlassian_cli/config.py

@@ -0,0 +1,57 @@
+"""Shared Atlassian Cloud configuration and session factory for atlassian_cli package."""
+
+import os
+import sys
+
+import requests
+from requests.auth import HTTPBasicAuth
+
+
+def load_env(path=None):
+    """Manually parse a .env file into a dict, skipping comments and blank lines."""
+    if path is None:
+        paths = [os.path.join(os.getcwd(), '.env'), os.path.join(os.path.dirname(__file__), '.env')]
+    else:
+        paths = [path]
+
+    for env_path in paths:
+        if os.path.exists(env_path):
+            with open(env_path, 'r') as file:
+                return dict(line.strip().split('=', 1) for line in file if not line.startswith('#') and '=' in line)
+    return {}
+
+
+def get_config():
+    """Return tuple (url, email, token) from .env or environment variables."""
+    env = load_env()
+    url = env.get('ATLASSIAN_URL', os.environ.get('ATLASSIAN_URL')) or \
+          env.get('CONFLUENCE_URL', os.environ.get('CONFLUENCE_URL'))
+    email = env.get('ATLASSIAN_EMAIL', os.environ.get('ATLASSIAN_EMAIL')) or \
+            env.get('CONFLUENCE_EMAIL', os.environ.get('CONFLUENCE_EMAIL'))
+    token = env.get('ATLASSIAN_TOKEN', os.environ.get('ATLASSIAN_TOKEN')) or \
+            env.get('CONFLUENCE_TOKEN', os.environ.get('CONFLUENCE_TOKEN'))
+
+    if not all([url, email, token]):
+        sys.stderr.write('ERR Missing ATLASSIAN_URL, ATLASSIAN_EMAIL, or ATLASSIAN_TOKEN\n'
+                         'Set them in .env or as environment variables.\n')
+        sys.exit(1)
+
+    return url.rstrip('/'), email, token
+
+
+def get_session(email, token):
+    """Create requests.Session with HTTPBasicAuth and JSON headers."""
+    session = requests.Session()
+    session.auth = HTTPBasicAuth(email, token)
+    session.headers.update({
+        'Accept': 'application/json',
+        'Content-Type': 'application/json'
+    })
+    return session
+
+
+def setup():
+    """Setup configuration and session, returning (session, base_url)."""
+    url, email, token = get_config()
+    session = get_session(email, token)
+    return session, url