4 - Atlassian CLI (acli) for Jira, Confluence, Rovo Dev, and org admin.
5 - Use when: working with Jira issues/projects/boards/sprints, Confluence
6 - pages/spaces/blogs, Atlassian org users, or Rovo Dev. Triggers on:
7 - jira, confluence, rovo, atlassian, work item, sprint, JQL, confluence page/space/blog.
4 + Atlassian tools for Jira, Confluence, and org admin. Triggers on: jira,
5 + confluence, rovo, atlassian, work item, sprint, JQL, confluence page/space/blog.
10 -#
Atlassian CLI (`acli`) 12 -CLI for Atlassian Cloud. Docs: <https://developer.atlassian.com/cloud/acli/>
14 -> **Note:** Official docs are incomplete. The command reference was last updated Oct 2024.
15 -> The official changelog stops at v1.3.15 (Mar 2026) — v1.3.16–1.3.18 have no release notes.
16 -> The `confluence` product is entirely absent from docs and changelog but works in the CLI.
17 -> This skill was built by testing against a real Atlassian Cloud instance.
13 +acli (preferred) → atlassian-cli (fallback) → web UI (last resort)
16 +| | acli | atlassian-cli |
17 +| ------------------------ | --------------- | ----------------- |
18 +| **Jira issues** | ✅ | ✅ |
19 +| **Jira projects/boards** | ✅ | ✅ |
20 +| **Confluence pages CRUD**| ❌ view only | ✅ create/edit/del|
21 +| **Confluence blogs CRUD**| ❌ create only | ✅ full CRUD |
22 +| **Confluence attachments**| ❌ | ✅ upload/download |
23 +| **Confluence search** | ❌ | ✅ CQL + text |
24 +| **Bitbucket** | ❌ | ✅ |
26 +| **Auth** | OAuth (browser) | API token |
28 +Docs: <https://developer.atlassian.com/cloud/acli/>
30 +> **Note:** acli's Confluence commands are undocumented and incomplete (no page
31 +> CRUD, no blog update/delete, no attachments). atlassian-cli fills those gaps
32 +> using the Confluence REST API v2 with basic auth (API token).
19 -> **Warning:** Don't confuse this with `atlassian-cli` (third-party Rust CLI by omar16100)
20 -> or Appfire ACLI (paid marketplace app). This skill covers only the official `acli` binary.
34 +> **Warning:** Don't confuse with `atlassian-cli` (third-party Rust, omar16100)
35 +> or Appfire ACLI (paid marketplace app). This skill covers only `acli` (official)
36 +> and `atlassian-cli` (omar16100).
22 38 ##
Prerequisites — STOP if missing 24 -Before any acli operation, verify dependencies:
28 -acli jira auth status
|| acli confluence auth status
43 +acli jira auth status
|| acli confluence auth status
46 +atlassian-cli --version
47 +atlassian-cli auth list
31 -**Missing `acli`?** Install: `brew install acli` or
32 -<https://developer.atlassian.com/cloud/acli/guides/install-acli/>
50 +**Missing `acli`?** Install: <https://developer.atlassian.com/cloud/acli/guides/install-acli/>
34 -**Not authenticated?** Run `acli <product> auth login`, then retry.
52 +**Missing `atlassian-cli`?** `brew install omar16100/atlassian-cli/atlassian-cli`
53 +or `cargo install atlassian-cli`.
36 -**Missing `pandoc` for Confluence publishing?** `md2confluence.py` requires
37 -`pandoc`. If absent, plain HTML works but code blocks won't have syntax
38 -highlighting. Report the gap — don't fall back to REST API.
40 -**Policy: never bypass acli with raw `curl`/REST API calls.** If acli can't do
41 -it, that's a documented gap (see "Known Gaps"). Stop and tell the user.
46 -acli <product> <resource> <action> [flags]
49 -Products: `jira`, `confluence`, `rovodev`, `admin`
55 +**Missing API token for atlassian-cli?**
56 +Create one at <https://id.atlassian.com/manage-profile/security/api-tokens>
57 +(click **Create API token**, not "with scopes"), then:
56 -acli confluence auth login
59 -acli admin auth login --email admin@example.com --token
< token.txt
62 -acli rovodev auth login
65 -acli jira auth status
66 -acli confluence auth status
60 +atlassian-cli auth login --profile default \
61 + --base-url https://YOUR-SITE.atlassian.net \
62 + --email you@example.com \
63 + --token
"$ATLASSIAN_API_TOKEN" --default
66 +**Policy: never bypass both tools with raw `curl`/REST API calls.** If neither
67 +tool can do it, that's a documented gap → use web UI.
69 +##
atlassian-cli parse errors 71 +atlassian-cli v0.3.x has a known JSON deserialization bug on list and delete
72 +responses (null fields in Confluence API v2). **Operations still succeed** —
73 +ignore the error and verify separately:
77 +atlassian-cli confluence page delete 12345 --force
81 +Rule of thumb: if you see `Failed to parse JSON response` the operation likely
82 +worked. Check status separately.
71 86 ###
Work Items (issues) 75 90 acli jira workitem create --summary
"Title" --project PROJ --type Task
76 -acli jira workitem create --summary
"Bug" --project PROJ --type Bug --assignee @me --label
"backend,urgent" 77 -acli jira workitem create --description
"plain text only" --description-file desc.txt -p PROJ -t Story -s
"Title" 80 -acli jira workitem create --generate-json
> workitem.json
91 +acli jira workitem create --assignee @me --label
"backend,urgent" -p PROJ -t Story -s
"Title" 92 +acli jira workitem create --generate-json
> workitem.json
82 93 acli jira workitem create --from-json workitem.json
85 96 acli jira workitem create-bulk --from-csv issues.csv
86 97 acli jira workitem create-bulk --from-json issues.json
89 100 acli jira workitem view KEY-123
90 -acli jira workitem view KEY-123 --fields summary,status,assignee,description --json
91 -acli jira workitem view KEY-123 --web
101 +acli jira workitem view KEY-123 --fields summary,status --json
94 102 acli jira workitem search --jql
"project = PROJ AND status = Open" --paginate
95 -acli jira workitem search --jql
"assignee = currentUser() AND sprint in openSprints()" --fields
"key,summary,priority" --json
96 -acli jira workitem search --jql
"project = PROJ" --csv --limit 50
97 -acli jira workitem search --filter 10001
103 +acli jira workitem search --jql
"assignee = currentUser()" --csv --limit 50
104 +acli jira workitem search --filter 10001
100 -acli jira workitem edit --key KEY-123 --summary
"Updated title" 101 -acli jira workitem edit --key KEY-1,KEY-2 --assignee user@example.com
102 -acli jira workitem edit --jql
"project = PROJ AND status = 'To Do'" --assignee @me
107 +acli jira workitem edit --key KEY-123 --summary
"Updated" 108 +acli jira workitem edit --jql
"project = PROJ" --assignee @me
109 +acli jira workitem transition --key KEY-123 --status Done --yes
110 +acli jira workitem transition --jql
"project = PROJ" --status
"In Progress" 105 -acli jira workitem transition --key KEY-123 --status
"In Progress" 106 -acli jira workitem transition --jql
"project = PROJ" --status Done --yes
109 113 acli jira workitem clone --key KEY-123 --to-project OTHER
114 +acli jira workitem delete --key KEY-123 --yes
112 -acli jira workitem comment create --key KEY-123 --body
"comment text" 113 -acli jira workitem comment create --key KEY-123 --body-file comment.txt
117 +acli jira workitem comment create --key KEY-123 --body
"text" 114 118 acli jira workitem comment list --key KEY-123
115 -acli jira workitem comment update --key KEY-123 --id COMMENT_ID --body
"updated" 116 -acli jira workitem comment delete --key KEY-123 --id COMMENT_ID
117 -acli jira workitem comment visibility --role --project PROJ
118 -acli jira workitem comment visibility --group
119 +acli jira workitem comment update --key KEY-123 --id ID --body
"updated" 120 +acli jira workitem comment delete --key KEY-123 --id ID
121 +acli jira workitem comment visibility --role --project PROJ
121 124 acli jira workitem link create --key KEY-1 --target KEY-2 --type
"Blocks" 122 125 acli jira workitem link list --key KEY-1
123 126 acli jira workitem link delete --key KEY-1 --target KEY-2 --type
"Blocks" 124 -acli jira workitem link type
127 +acli jira workitem link type
127 130 acli jira workitem attachment list --key KEY-123
128 -acli jira workitem attachment delete --key KEY-123 --id ATTACHMENT_ID
131 +acli jira workitem attachment delete --key KEY-123 --id ID
131 134 acli jira workitem assign --key KEY-123 --assignee user@example.com
132 135 acli jira workitem archive --key KEY-123
133 136 acli jira workitem unarchive --key KEY-123
134 -acli jira workitem delete --key KEY-123 --yes
135 137 acli jira workitem watcher list --key KEY-123
136 138 acli jira workitem watcher remove --key KEY-123 --user user@example.com
141 +###
Projects, Boards, Sprints, Filters, Fields 142 -acli jira project list --limit 20
144 +acli jira project list --limit 20
143 145 acli jira project view PROJ
144 -acli jira project create --key PROJ --name
"Project Name" 145 -acli jira project update PROJ --name
"New Name" 146 -acli jira project archive PROJ
147 -acli jira project delete PROJ
146 +acli jira project create --key PROJ --name
"Name" 150 -###
Boards & Sprints 153 148 acli jira board search --project PROJ
154 -acli jira board get BOARD_ID --json
155 149 acli jira board list-sprints BOARD_ID
156 150 acli jira sprint create --board BOARD_ID --name
"Sprint 1" 157 -acli jira sprint view SPRINT_ID
158 151 acli jira sprint list-workitems SPRINT_ID
159 -acli jira sprint update SPRINT_ID --state closed
165 153 acli jira filter list
166 -acli jira filter search --jql
"project = PROJ" 167 -acli jira filter get --id FILTER_ID
168 -acli jira filter add-favourite --id FILTER_ID
169 -acli jira filter update --id FILTER_ID --jql
"..." 175 -acli jira field create --name
"My Field" --type text
176 -acli jira field update --id customfield_12345 --name
"New Name" 177 -acli jira field delete --id customfield_12345
178 -acli jira field cancel-delete --id customfield_12345
184 -acli jira dashboard search
154 +acli jira field create --name
"Field" --type text
189 -> Not documented in official acli docs. Verified against a real Confluence Cloud
190 -> instance (v1.3.18). REST API also out of scope — no way to reuse acli's OAuth
191 -> token, and maintaining a separate API token is too much ceremony. Gaps = web UI.
193 -###
Pages (view only) 159 +###
Pages — use atlassian-cli for create/edit/delete 196 163 acli confluence page view --id PAGE_ID
197 164 acli confluence page view --id PAGE_ID --json
198 165 acli confluence page view --id PAGE_ID --body-format storage
199 -acli confluence page view --id PAGE_ID --body-format atlas_doc_format
200 -acli confluence page view --id PAGE_ID --include-labels --include-version
201 166 acli confluence page view --id PAGE_ID --include-direct-children
169 +atlassian-cli confluence page list --space SPACE_ID --limit 25
172 +atlassian-cli confluence page get PAGE_ID
175 +echo '<p>Content here</p>' > /tmp/page.html
176 +atlassian-cli confluence page create \
177 + --space SPACE_ID --title
"New Page" --body /tmp/page.html
179 +atlassian-cli confluence page create \
180 + --space SPACE_ID --title
"Child" --parent PARENT_ID --body /tmp/page.html
183 +echo '<p>Updated content</p>' > /tmp/page_v2.html
184 +atlassian-cli confluence page update PAGE_ID --body /tmp/page_v2.html --message
"update note" 187 +atlassian-cli confluence page delete PAGE_ID --force
190 +atlassian-cli confluence page add-label --id PAGE_ID --label mylabel
191 +atlassian-cli confluence page remove-label --id PAGE_ID --label mylabel
194 +atlassian-cli confluence page comments PAGE_ID
195 +atlassian-cli confluence page add-comment --id PAGE_ID --body
"comment text" 202 +acli confluence blog create --space-id SPACE_ID --title
"Post" --body
"<p>Text</p>" 203 +acli confluence blog create --space-id SPACE_ID --title
"Post" --from-file content.html
204 +acli confluence blog create --from-json payload.json
207 +acli confluence blog view --id BLOG_ID
208 +acli confluence blog list --space-id SPACE_ID
211 +echo '<p>Updated</p>' > /tmp/blog.html
212 +atlassian-cli confluence blog update BLOG_ID --body /tmp/blog.html
213 +atlassian-cli confluence blog delete BLOG_ID --force
207 219 acli confluence space list
208 220 acli confluence space view --key SPACEKEY
209 -acli confluence space create --key SPACEKEY --name
"Space Name" --description
"desc" 221 +acli confluence space create --key SPACEKEY --name
"Name" 210 222 acli confluence space update --key SPACEKEY --name
"New Name" 211 223 acli confluence space archive --key SPACEKEY
212 224 acli confluence space restore --key SPACEKEY
227 +###
Attachments — atlassian-cli only 218 -acli confluence blog create --space-id SPACE_ID --title
"Post" --body
"<p>Content</p>" 219 -acli confluence blog create --space-id SPACE_ID --title
"Draft" --status draft --body
"text" 220 -acli confluence blog create --space-id SPACE_ID --title
"Post" --from-file content.html
221 -acli confluence blog create --from-json payload.json
222 -acli confluence blog list --space-id SPACE_ID
223 -acli confluence blog view --id BLOG_ID
230 +atlassian-cli confluence attachment upload --page-id PAGE_ID --file ./diagram.png
231 +atlassian-cli confluence attachment list --page-id PAGE_ID
232 +atlassian-cli confluence attachment download --id ATTACHMENT_ID --output ./out.png
233 +atlassian-cli confluence attachment delete --id ATTACHMENT_ID
236 +###
Search — atlassian-cli only 239 +atlassian-cli confluence search cql --cql
"space = DEV and type = page" --limit 10
240 +atlassian-cli confluence search text --query
"meeting notes" --limit 10
241 +atlassian-cli confluence search in-space --space DEV --query
"api docs" 226 244 ###
Finding your space ID 238 -AI coding agent (beta). Requires separate API token from
239 -<https://go.atlassian.com/rovo-dev-api-token>.
256 +### acli — OAuth (browser)
242 -acli rovodev auth login
259 +acli jira auth login # browser OAuth
260 +acli confluence auth login # browser OAuth
261 +acli admin auth login --email admin@example.com --token < token.txt
262 +acli rovodev auth login # token from https://go.atlassian.com/rovo-dev-api-token
265 +###
atlassian-cli — API token 269 +atlassian-cli auth login --profile default \
270 + --base-url https://SITE.atlassian.net --email you@example.com
273 +export ATLASSIAN_URL
="https://SITE.atlassian.net" 274 +export ATLASSIAN_EMAIL
="you@example.com" 275 +export ATLASSIAN_API_TOKEN
="your-token" 278 +Create token: <https://id.atlassian.com/manage-profile/security/api-tokens>
283 +acli rovodev auth login
250 -acli admin auth login --email admin@example.com --token
< token.txt
252 290 acli admin user activate --account-id USER_ID
253 291 acli admin user deactivate --account-id USER_ID
254 292 acli admin user delete --account-id USER_ID
255 -acli admin user cancel-delete --account-id USER_ID
260 299 | Flag | Effect |
261 300 | ------------ | -------------------------- |
262 301 | `--json` | JSON output |
263 -| `--csv` | CSV output (search only) |
302 +| `--csv` | CSV (search only) |
264 303 | `--web` | Open in browser |
265 -| `--paginate` | Fetch all pages of results |
304 +| `--paginate` | Fetch all pages |
266 305 | `--limit N` | Cap results |
267 -| `--yes`/`-y` | Skip confirmation prompts |
306 +| `--yes`/`-y` | Skip confirmation |
311 +| ----------------- | ------------------------------- |
312 +| `-f json` | JSON output |
313 +| `-f csv` | CSV output |
314 +| `-f yaml` | YAML output |
315 +| `-f table` | Table (default) |
316 +| `-f quiet` | IDs only |
269 318 ##
JQL Quick Reference 284 333 Combine with `AND` / `OR` / `NOT`. Group with `()`.
285 -Use `--paginate` for large result sets.
287 335 ## Rich Formatting
289 -### ADF for rich Jira descriptions and comments
337 +### ADF for rich Jira descriptions (acli)
291 -acli's `--description` and `--body` accept **plain text only**. Jira wiki markup
292 -(`h1.`, `*bold*`, `{code}`) is stored as literal text — NOT rendered.
294 -For rich formatting, build ADF JSON and use `--from-json`:
339 +acli's `--description` accepts **plain text only**. Jira wiki markup is stored
340 +as literal text. For rich formatting, use ADF JSON via `--from-json`:
297 -acli jira workitem create --generate-json > template.json # scaffold
343 +acli jira workitem create --generate-json > template.json
300 -Verified ADF node types:
346 +Verified ADF nodes: `heading`, `paragraph`, `text` (marks: `strong`/`em`/`code`),
347 +`codeBlock`, `bulletList`, `orderedList`, `table`, `blockquote`.
302 -| ADF node | Renders as |
303 -| ------------- | ------------------ |
304 -| `heading` | h1–h6 heading |
305 -| `paragraph` | text paragraph |
306 -| `text` + marks| bold/em/code/... |
307 -| `codeBlock` | syntax highlighted |
308 -| `bulletList` | unordered list |
309 -| `orderedList` | numbered list |
310 -| `table` | data table |
311 -| `blockquote` | block quote |
349 +###
Confluence pages — HTML storage format (atlassian-cli) 313 -Mark types: `strong`, `em`, `code`, `strike`, `underline`, `link`.
315 -Example ADF paragraph:
319 - "type":
"paragraph",
321 - {
"type":
"text",
"text":
"Normal "},
322 - {
"type":
"text",
"text":
"bold",
"marks": [{
"type":
"strong"}]},
323 - {
"type":
"text",
"text":
" "},
324 - {
"type":
"text",
"text":
"italic",
"marks": [{
"type":
"em"}]},
325 - {
"type":
"text",
"text":
" "},
326 - {
"type":
"text",
"text":
"code",
"marks": [{
"type":
"code"}]}
331 -###
Confluence: Markdown → HTML with Syntax Highlighting 333 -Confluence accepts HTML in `--body` / `--from-file`. Plain pandoc HTML works for
334 -most elements but **code blocks render as unstyled text** — Confluence ignores
335 -pandoc's CSS `<span>` classes.
337 -Use `md2confluence.py` (in this skill's directory). Runs
338 -`pandoc -f markdown -t html --no-highlight` then replaces `<pre class="LANG">`
339 -blocks with `<ac:structured-macro ac:name="code">` for proper Confluence syntax
351 +atlassian-cli's `--body` takes a **file path** containing Confluence storage
352 +format HTML. For markdown with syntax-highlighted code blocks, use
353 +`md2confluence.py` (in this skill's directory):
343 -python3 md2confluence.py input.md
> output.html
344 -acli confluence blog create --space-id SPACE_ID --title
"Title" --from-file output.html
356 +python3 md2confluence.py input.md
> /tmp/page.html
357 +atlassian-cli confluence page create --space SPACE_ID --title
"Title" --body /tmp/page.html
347 -**Requires:** `pandoc` in PATH. If missing, report the gap to the user.
349 -###
Pandoc Jira markup — read only 353 -pandoc -f jira -t markdown input.jira
356 -pandoc -f markdown -t jira input.md
359 -acli does NOT accept Jira wiki markup for descriptions or comments. Only useful
360 -for converting existing wiki markup to readable markdown.
360 +**Requires:** `pandoc` in PATH. Converts pandoc code blocks to
361 +`<ac:structured-macro ac:name="code">` for proper Confluence highlighting.
362 363 ##
Common Patterns 367 368 acli jira workitem search --jql "assignee = currentUser() AND type = Bug AND sprint in openSprints()" --paginate --json
371 +### Create a Confluence page from markdown
374 +python3 md2confluence.py report.md > /tmp/report.html
375 +atlassian-cli confluence page create --space SPACE_ID --title "Report" --body /tmp/report.html
378 +###
Upload attachment to a page 381 +atlassian-cli confluence attachment upload --page-id PAGE_ID --file ./screenshot.png
370 384 ###
Bulk transition to Done 382 396 ###
Export issues as CSV 385 -acli jira workitem search --jql
"project = PROJ" --fields
"key,summary,status,assignee" --csv
> issues.csv
399 +acli jira workitem search --jql
"project = PROJ" --fields
"key,summary,status" --csv
> issues.csv
388 -###
Publish markdown as Confluence blog with code highlighting 391 -python3 md2confluence.py report.md
> /tmp/report.html
392 -acli confluence blog create --space-id SPACE_ID --title
"Report" --from-file /tmp/report.html
395 -##
Known Gaps (acli v1.3.18) 397 404 If you hit any of these, **stop and report to the user.** Do not fall back to
401 408 | --------------------------------------------- | ----------------------- |
402 -| No `confluence page create/update/delete` | ⛔ use web UI |
403 -| No `confluence blog update/delete` | ⛔ use web UI |
404 -| No `jira workitem attachment` upload | ⛔ use web UI |
405 -| No raw API proxy subcommand | ⛔ not possible via acli|
406 -| REST API access (separate token required) | ⛔ out of scope — web UI |
407 -| `project list` requires `--limit`/`--paginate`| always pass one |
408 -| `--json` on `auth status` not supported | use plain text output |
409 -| `--description` only accepts plain text | use `--from-json` + ADF |
410 -| Jira wiki markup not rendered by acli | use ADF JSON |
411 -| Pandoc HTML code blocks unstyled in Confluence| use `md2confluence.py` |
412 -| Confluence commands absent from official docs | undocumented, may change|
413 -| v1.3.16–1.3.18 have no changelog entries | unknown what else changed|
414 -| No `acli jira auth login --web` in docs | works anyway (OAuth) |
409 +| acli: no `confluence page create/update/delete`| ✅ use atlassian-cli |
410 +| acli: no `confluence blog update/delete` | ✅ use atlassian-cli |
411 +| acli: no attachment upload | ✅ use atlassian-cli |
412 +| acli: no Confluence search | ✅ use atlassian-cli |
413 +| acli: Confluence commands absent from docs | undocumented, may change|
414 +| atlassian-cli: page list parse error | cosmetic — list works |
415 +| atlassian-cli: delete ops show parse error | ops succeed — verify separately |
416 +| atlassian-cli: `--body` is file path only | write temp file |
417 +| No `jira workitem attachment` upload (acli) | use web UI |
418 +| v1.3.16–1.3.18 have no changelog entries | unknown what changed |
416 420 ##
Troubleshooting 418 422 ###
"failed to parse JQL query" 420 -JQL field values are case-sensitive. Quote strings with spaces.
421 -Operators: `=` (exact), `~` (fuzzy/contains), `!=`, `!~` (not contains).
424 +JQL values are case-sensitive. Quote strings with spaces.
425 +Operators: `=` `~` `!=` `!~`.
427 +###
"Failed to parse JSON response" (atlassian-cli) 426 -acli jira auth status
427 -acli jira auth login
429 +Known bug in v0.3.x — the operation usually succeeded. Verify separately:
430 +`acli confluence page view --id ID` or `atlassian-cli confluence page get ID`.
430 -###
"site admin must authorize this app" 432 +###
"site admin must authorize this app" (acli) 432 -Since v1.3.15 — OAuth scopes changed. Site admin must re-approve:
433 -`acli jira auth login` → select "Web" → approve the site.
434 +Since v1.3.15 — OAuth scopes changed. Site admin re-approves via
435 +`acli jira auth login` → select "Web".
435 437 ###
Rate limiting 437 -Use `--limit` to cap results. Avoid `--paginate` in tight loops.
439 +acli: use `--limit` to cap results. Avoid `--paginate` in tight loops.
439 441 ###
Pandoc not found 441 -`md2confluence.py` requires `pandoc`. Install: `brew install pandoc` or system
442 -package manager. Plain `pandoc -t html` still works for non-code content.
443 +`md2confluence.py` requires `pandoc`. Install: `brew install pandoc`.