atlassian

Files (3)

• LICENSE
• README.md
• SKILL.md

SKILL.md (first lines)

<!-- Based on the acli skill from https://github.com/leweii/atlassian-cli, MIT licensed. -->

# Atlassian CLI (acli)

## Overview

The Atlassian CLI (`acli`) provides command-line access to Jira, Confluence, and other Atlassian products. **Core principle:** Always check authentication first, use correct command structure, and leverage batch operations.

This reference was verified against **acli 1.3.39-stable** (October 2026). If `acli --version` reports a newer release, do not assume this reference is complete: check `acli <product> --help` for the current command surface, and the upstream repo (https://github.com/leweii/atlassian-cli) or https://developer.atlassian.com/cloud/acli/ for release notes on new features.

## When to Use

- Creating, searching, or updating Jira issues
- Managing sprints, boards, or projects
- Working with Confluence spaces
- Bulk operations on multiple items
- Generating reports in CSV/JSON format
- Automating Atlassian workflows

**When NOT to use:**
- When web UI is more appropriate (one-off visual tasks)
- When API tokens/integrations are already available

## acli vs Atlassian MCP

Atlassian also ships a hosted remote MCP server (Rovo MCP v2, `https://mcp.atlassian.com/v2/mcp`). When an Atlassian MCP connection is available in your environment (pi, Claude Code), split work between the two:

**Prefer the MCP server when:**
- Single-issue reads and writes (Jira get/search/create/edit/transition/comment, Confluence get/create/update/search are first-class tools with richer, self-describing responses)
- Semantic search across Jira/Confluence (Rovo `search`)
- Cross-product relationship queries (Teamwork Graph: `getGraphContext`/`getGraphObject`)
- Work in products acli does not cover: Compass, Bitbucket, Teams, Goals, Focus (via `discover` + `executeRead`/`executeWrite`/`executeDestructive`, ~315 operations)
- Destructive operations should be separately permission-gated (MCP exposes them as a dedicated `executeDestructive` tool)

**Prefer acli when:**
- Bulk operations: `create-bulk`, or `edit`/`transition`/`assign` with `--jql`/`--filter`/`--key` plus `--yes`. The MCP server has no batching primitive; an agent would have to loop one call per issue
- Reports and data export: `--csv`, `--fields`, `--count`, `--paginate`
- Sprint, board, worklog, release, and field-history questions: these need purpose-built endpoints, not JQL; acli has first-class `sprint`/`board` entities
- Saved-filter targeting (`--filter <id>`)
- No MCP connection is configured

Both cover the core loop (read, JQL/CQL search, create, edit, transition, comment) with rough parity; either is fine there.

**MCP version note:** v2 (GA 2026-09-08) exposes a curated 21-tool list plus the `discover`/`execute` family; it renamed several v1 tools (`getConfluencePage` became `getConfluenceContent`, `addCommentToJiraIssue` became `addOrEditJiraIssueComment`) and removed most v1-era granular tools behind `discover`/`execute`. A cached v1 tool list (about 40 tools) is stale: probe the server with `tools/list` instead of trusting caches.

## Authentication - FIRST STEP ALWAYS

```mermaid
flowchart TD
    A([User requests acli command]) --> B[Check auth status]
    B --> C{Authenticated?}
    C -->|yes| D[Run acli command]
    C -->|no| E[Explain: acli auth login]
```

**Before ANY acli operation:**
```bash
# Check if authenticated
acli auth status

# If not authenticated, login first
acli auth login
```

## Command Structure

**Format:** `acli <product> <entity> <action> [flags]`

**DO NOT use old-style syntax with `--action` flag.**

```bash
# WRONG - old syntax that doesn't work
acli jira --action getIssueList --jql "..."

# CORRECT - modern syntax
acli jira workitem search --jql "..."
```

## Quick Reference

### Common Products
- `auth` - Authentication management (multiple accounts, OAuth)
- `jira` - Jira Cloud commands
- `confluence` - Confluence Cloud commands
- `admin` - Admin operations
- `guard` - Atlassian Guard CLI
- `rovodev` - Rovo Dev, Atlassian's AI coding agent (Beta)
- `config` - Configuration settings

### Jira Entities & Actions

| Entity | Common Actions | Example |
|--------|---------------|---------|
| `workitem` | search, create, create-bulk, edit, view, transition, assign, delete, archive, unarchive, clone, link, attachment, watcher, list-watchers | `acli jira workitem search --jql "project = TEAM"` |
| `project` | list, view, create, update, delete, archive, restore | `acli jira project list` |
| `sprint` | create, update, view, delete, list-workitems | `acli jira sprint view --id 123` |
| `board` | search, view (get is deprecated), create, delete, list-sprints, list-projects | `acli jira board list-sprints --id 42` |
| `workitem comment` | create, list, update, delete, visibility | `acli jira workitem comment create --key KEY-1 --body "text"` |

### Confluence Entities

| Entity | Actions | Example |
|--------|---------|---------|
| `space` | list, view, create, update, archive, restore | `acli confluence space list` |
| `page` | view | `acli confluence page view --id 12345` |
| `blog` | list, view, create | `acli confluence blog list --space TEAM` |

**Confluence `page view` caveats (verified against acli 1.3.39-stable):**
- The page ID must be passed as `--id <id>`; the positional form `acli confluence page view 12345` fails with `required flag(s) "id" not set`
- The body is empty (`"body": {}`) unless you pass an explicit `--body-format` (e.g. `storage`, `view`, `atlas_doc_format`)
- Without `--json`, only the metadata table is printed and the body is never shown; use `--body-format view --json` and read `.body.view.value` to get readable page content
- `storage` and `view` output is raw XHTML (Confluence macros, `local-id` attributes); there is no markdown/ADF conversion

## Batch Operations

**Use JQL, filters, or key lists to operate on multiple items:**

```bash
# Edit multiple issues with JQL

From lucaspimentel/agent-skills, MIT.

More from lucaspimentel/agent-skills