atlassian-cli

Fast CLI tools for Atlassian Cloud — built for AI agents, loved by humans.

---

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

pip install atlassian-cli

Or from source:

pip install git+https://github.com/catapultcx/atlassian-cli.git

Setup

Create a config file with your credentials:

mkdir -p ~/.config/atlassian-cli
cat > ~/.config/atlassian-cli/config <<EOF
ATLASSIAN_URL=https://your-site.atlassian.net
ATLASSIAN_EMAIL=you@example.com
ATLASSIAN_TOKEN=your-api-token
EOF
chmod 600 ~/.config/atlassian-cli/config

The CLI looks for credentials in this order (first match wins):

1. $ATLASSIAN_CLI_CONFIG (explicit path override)
2. ./.env in the current working directory
3. $XDG_CONFIG_HOME/atlassian-cli/config (defaults to ~/.config/atlassian-cli/config)
4. ~/.atlassian-cli/config
5. Environment variables (ATLASSIAN_URL, ATLASSIAN_EMAIL, ATLASSIAN_TOKEN)

Get your API token at https://id.atlassian.com/manage-profile/security/api-tokens

Legacy CONFLUENCE_URL / CONFLUENCE_EMAIL / CONFLUENCE_TOKEN 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.

# 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

Blog posts

Create, read, update, and delete blog posts in any Confluence space.

# Create a blog post
confluence blog-create POL "Q1 Product Update"
confluence blog-create POL "Release Notes" --body "What's new this quarter..."
confluence blog-create POL "Deep Dive" --file /path/to/adf.json
confluence blog-create POL "Retrospective" --body "..." --created-at 2024-01-15T10:00:00Z

# Download a blog post
confluence blog-get 123456

# Edit locally and upload
confluence blog-get 123456
# ... edit the ADF JSON file ...
confluence blog-put 123456 --message "Added screenshots"

# Update title and/or body directly
confluence blog-update 123456 --title "Q1 Update (Revised)"
confluence blog-update 123456 --body "Updated content here" -m "Corrections"
confluence blog-update 123456 --created-at "2024-06-01T08:00:00Z"

# List blog posts in a space
confluence blog-list POL
confluence blog-list POL --include-draft

# Delete a blog post
confluence blog-delete 123456

Comments

Read, reply to, and resolve inline and footer comments on pages.

# List all comments on a page
confluence comments 9268920323

# List only open/unresolved comments
confluence comments 9268920323 --open

# Reply to an inline comment
confluence comment 10226663432 "Fixed — updated the wording"

# Reply to a footer comment
confluence comment 10226663432 "Noted, will action" --footer

# Resolve an inline comment
confluence resolve 10226663432

# Reopen a resolved comment
confluence resolve 10226663432 --reopen

Jira CLI

Issues

Full CRUD on Jira issues via REST API v3.

# 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.

# 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.

# 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
  confluence.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

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