acli
Skill26 starsChanged 10 days agoMITView on GitHub
Atlassian CLI (official `acli` binary) for Jira Cloud, Confluence Cloud, and org admin tasks from the terminal. Use whenever the user wants to create, view, edit, transition, assign, clone, archive, comment on, link, or bulk-operate on Jira work items; list or manage projects, boards, sprints, filters, dashboards, or custom-field definitions; create or update Confluence spaces, pages, or blog posts; activate/deactivate users at the org level; or authenticate to Atlassian from a shell or CI pipeline. Triggers on: `acli`, Atlassian CLI, Jira from the terminal, Confluence from the terminal, bulk Jira operations, scripting Jira, automate Jira tickets, transition a bunch of issues, create issues from a JSON/CSV file, CI pipeline that touches Jira, log in to Jira CLI, switch Atlassian sites, API-token auth for Jira. Use this skill even when the user does not say the word `acli` — if the task is CLI-driven Jira or Confluence work, this is the right tool. Do NOT use for: Atlassian MCP server work (that is a different integration), REST-API-only workflows where no CLI is involved, Bitbucket command-line needs (acli does not cover Bitbucket), or the legacy Appfire/Bob Swift `acli` tool (a different product that happens to share the binary name). The Atlassian MCP server is OPT-IN, documented in agentic-qa-core/references/mcp-atlassian-optin.md.
- Reads credentials
- Installs packages
5 other projects use a version of this.
Adopted by
Most recently taken up by
- fmind/dottheir own version, first seen Nov 15, 2026
- fmind/dotfilestheir own version, first seen Nov 15, 2026
- jaltez/acli-skilltheir own version, first seen Oct 13, 2026
- hussainweb/skillstheir own version, first seen Sep 18, 2026
- Alcamech/skillstheir own version, first seen Aug 21, 2026
Other versions5 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 5
- fmind/dot★ 13same name
- fmind/dotfiles★ 13same name
- hussainweb/skills★ 3same name
- Alcamech/skills★ 0same name
- jaltez/acli-skill★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository30 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- agentic-qa-coreSkill
- agentic-qa-onboardSkill
- bug-screenshot-annotationSkill
- business-api-contextSkill
- business-data-contextSkill
- business-domain-contextSkill
- business-e2e-contextSkill
- evidence-artifactSkill
- exploratory-testingSkill
- framework-developmentSkill
- git-flow-masterSkill
- infra-contextSkill
- iql-contextSkill
- jira-administrationSkill
- judgment-daySkill
- orca-orchestrationSkill
- project-contextSkill
- project-discoverySkill
- pr-review-leadSkill
- regression-testingSkill
- session-handoffSkill
- shift-left-testingSkill
- sprint-conductorSkill
- sprint-testingSkill
- test-automationSkill
- test-documentationSkill
- test-framework-adaptationSkill
- xray-cliSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
34 rules. 0 are common, 9 are distinctive, and 25 are very specific to this project.
0
Common
Most of the 5 edited versions we read keep these.
9
Distinctive
This author's own choices. Worth a look.
25
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 20
DO: pass --paginate (or an explicit --limit) on any search whose result is counted, iterated, or decided on.
- Distinctive: line 21
DO NOT: read exit 0 as proof a subcommand exists.
- Distinctive: line 22
DO: verify auth status before any bulk mutation.
- Distinctive: line 23
DO: pass the non-interactive confirmation flag on every mutating command in CI, or the command hangs waiting on stdin.
- Very specific: line 24
DO NOT: hand-author raw ADF JSON, and do not pass Markdown to a rich-text flag — the CLI never converts it and stores the literal …
- Distinctive: line 25
DO: let the converter's validation gate run on every ADF document before publishing, and round-trip read the field after writing.
- Very specific: line 27
DO NOT: assume workitem edit takes custom-field values.
- Very specific: line 29
DO NOT: copy an example out of the vendor's own --help.
- Very specific: line 30
DO NOT: hardcode a customfield_NNNNN id in a script or in generated output.
- Very specific: line 31
DO NOT: read the Atlassian host from an environment variable.
- Very specific: line 32
WHEN creating an issue link: --out / --in are empirically INVERTED against Jira's semantics — --out takes the prerequisite, --in the …
- Distinctive: line 33
DO: capture and surface the trace id from any backend failure.
- Distinctive: line 34
WHEN the operation is a known blind spot (enumerate custom fields, edit custom-field values, manage workflows / issue types / versions / …
- Very specific: line 35
WHEN a REST fallback needs ATLASSIAN_EMAIL / ATLASSIAN_API_TOKEN: run it inside the .env loader (bunx varlock run --filter …
- Very specific: line 36
DO: prefer API-token auth in scripted contexts, and pin the binary to an explicit version in production pipelines — tracking latest has …
- Very specific: line 58
Read complementary_categories from this skill's frontmatter (issue-tracker).
- Very specific: line 71
If acli is not installed or authenticated, fall back to the Atlassian MCP server (MCP tool namespace: mcp__atlassian__* or similar — check …
- Very specific: line 104
Every level has --help. Use it aggressively when unsure:
- Distinctive: line 180
When the selector matches many items, the command is a batch operation.
- Very specific: line 187
All list/search/view commands support three shapes:
- Distinctive: line 359
When the task is to populate N work items with M rich-text fields each, the converter scales linearly with negligible overhead.
- Very specific: line 361
Write one generator script (generate.ts) that holds the per-field Markdown content for every item as inline string literals.
- Very specific: line 442
When this becomes unnecessary: If Atlassian adds an additionalAttributes-style channel to acli workitem edit, retire this workaround and …
- Distinctive: line 455
T1.: NEVER hand-author raw ADF JSON for descriptions, comments, or rich-text custom fields.
- Very specific: line 456
T2.: NEVER hardcode Jira customfield_NNNNN IDs in scripts or AI output that consumes acli.
- Very specific: line 457
T3.: NEVER assume acli accepts custom-field input on workitem edit.
- Very specific: line 458
T4.: NEVER run a bulk acli mutation (transition, edit, comment, link, archive) without first verifying acli jira auth status.
- Very specific: line 465
--paginateis opt-in: Default limit is server-side (30–50 depending on command). - Very specific: line 468
Transitions match by status name, not transition ID: When two transitions lead to the same status with different validators, the CLI picks …
- Very specific: line 542
Default to Markdown authoring for any rich-text field: Never pass raw markdown to --description, --body, or any custom-field value — acli …
- Very specific: line 545
Always pass
--paginate: when a downstream script consumes the result. - Very specific: line 548
Do not invent flags: When unsure, run acli <path> --help — it is authoritative and version-pinned to the installed binary.
- Very specific: line 550
Know what
aclicannot do: All of the following require REST or MCP — acli does not cover them (confirm against the installed binary with … - Very specific: line 555
Add a work item to a sprint (Atlassian tracked it as JRACLOUD-97107 when this was written).
“Common” is measured: kept by at least 6 in 10 of the 5 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Atlassian CLI (acli)
acli is Atlassian's official command-line tool for Jira Cloud, Confluence Cloud, and org admin operations. It replaces terminal-based Jira automation that previously required raw REST calls, and unifies Jira + Confluence + admin actions behind one binary with one credential store per product.
This skill teaches how to drive acli for any intent: one-off commands, batch mutations, scripted pipelines, and CI jobs. Repo-specific integration (how this skill plugs into the host repo's workflow, TMS modality, project conventions, anti-patterns) lives in the companion file <repo-core>/references/acli-integration.md — load it on demand. See "Navigation" below.
Compact Rules
- DO: pass
--paginate(or an explicit--limit) on any search whose result is counted, iterated, or decided on. Pagination is opt-in and truncation is silent — there is no warning. - DO NOT: read exit 0 as proof a subcommand exists. An unknown subcommand falls back to the parent help and exits 0. Check that the help body actually changed, and never invent a flag — every multi-word flag is kebab-case.
- DO: verify auth status before any bulk mutation. Auth is per-product (jira / confluence / admin / global are separate sessions) and a silent expiry leaves the batch half-applied with no clean rollback.
- DO: pass the non-interactive confirmation flag on every mutating command in CI, or the command hangs waiting on stdin.
- DO NOT: hand-author raw ADF JSON, and do not pass Markdown to a rich-text flag — the CLI never converts it and stores the literal characters. Author in Markdown, convert with
scripts/md-to-adf.ts, pass the ADF. - DO: let the converter's validation gate run on every ADF document before publishing, and round-trip read the field after writing. The gate catches node-level errors; only the read-back catches Jira's silent server-side coercion.
- DO: measure the serialized ADF of every rich-text value (description, comment, rich-text custom field) before writing it:
jq -c . <file>.adf.json | wc -mmust stay at or under 30000. Jira's cap counts the ADF JSON, not the Markdown, and ADF is several times longer. Over budget → STOP and propose which sections move where; never truncate, never split one value across two fields or comments. Detail: "Size budget" under "Publishing rich text". - DO NOT: assume
workitem edittakes custom-field values. It hard-rejects every shape with exit 1; editing a custom field on an EXISTING item works only through the REST PUT path. - DO NOT: expect
workitem editto set an issue's COMPONENTS either. There is no flag and no--from-jsonkey, so the edit succeeds while leaving components untouched and says nothing. Set them at create time, or change them through the same REST PUT path as custom fields. - DO NOT: copy an example out of the vendor's own
--help. Several omit the subcommand the flags actually live on (workitem comment --key …instead ofworkitem comment create --key …) and fail withunknown flag. The forms in this skill's references are the tested ones. - DO NOT: hardcode a
customfield_NNNNNid in a script or in generated output. Resolve it through the host project's slug catalog — ids differ per workspace, slugs travel. - DO NOT: read the Atlassian host from an environment variable. It lives in
.agents/project.yamlunderissue_tracker.atlassian_urland is resolved through the accessor; an inherited copy in the environment goes stale and points scripts at the wrong site. - WHEN creating an issue link:
--out/--inare empirically INVERTED against Jira's semantics —--outtakes the prerequisite,--inthe dependent. Verify the direction by listing the link afterwards, and recreate with swapped flags if it landed backwards. - DO: capture and surface the trace id from any backend failure. It is the only debug signal, and Atlassian Support needs it.
- WHEN the operation is a known blind spot (enumerate custom fields, edit custom-field values, manage workflows / issue types / versions / components, attachments, watchers, add an item to a sprint): route through REST or the opt-in Atlassian MCP rather than forcing the CLI.
- WHEN a REST fallback needs
ATLASSIAN_EMAIL/ATLASSIAN_API_TOKEN: run it inside the.envloader (bunx varlock run --filter ATLASSIAN_EMAIL,ATLASSIAN_API_TOKEN -- sh -c '...') or through a bundled script that loads.envitself (scripts/jira-attach-media.ts). NEVER export them,source .envor print them in the agent's shell. - DO: prefer API-token auth in scripted contexts, and pin the binary to an explicit version in production pipelines — tracking
latesthas caused same-day mass failures.
Read full SKILL.md when: composing a specific command, publishing rich text, running the REST PUT workaround, or working any surface outside Jira work items.
Why this skill exists
acli has several traits that make it easy to misuse:
- Silent pagination truncation.
workitem searchwithout--paginatereturns the first page only — no warning. Scripts that count or iterate keys read the wrong number of items. - Auth is per-product.
acli jira auth logindoes not authenticateacli admin,acli confluence, oracli rovodev. There is also a top-levelacli authfor global OAuth (newer surface). Each scope has its own session. - The "work item" vs "issue" split. The CLI renamed commands (
jira issue→jira workitem) but the JSON response still has a top-levelissues[]array and CSV inputs still useissueType/parentIssueIdspellings. Mixing old and new terminology in the same script works, but confuses readers. - Unknown subcommands fail silently. Typing
acli jira workflow --helpdoes NOT error — it falls back toacli jira --helpwith exit 0. So "no error" ≠ "command exists". Always verify by checking the help body actually changed. - Hard limits the docs do not advertise.
aclicannot list custom fields, edit custom-field values on existing items, manage workflows, manage issue types, or touch project versions/components. Seereferences/gotchas.md.
The body below covers the core that applies to almost every session. The references/ directory holds the deep material — load only the one you need.
Composable Skills (auto-resolved at skill entry)
acli is itself the canonical issue-tracker skill. The category typically has no T3 skills that overlap — acli is the tool surface, not a borrower of community skills.
Steps for protocol consistency:
- Read
complementary_categoriesfrom this skill's frontmatter (issue-tracker). - Scan the skills actually installed (the host repo's strategy doc §3.1): the session's skill list plus every
.agents/skills/*/SKILL.mdon disk, git-ignored community folders included..agents/skills/REGISTRY.mdlists committed skills only, so it is never this scan. - Apply the threshold rule per the host repo's skill-composition strategy doc (T1 / T3 silent; T4 silent only when a doctrine names it for this moment, otherwise ASK).
- The Atlassian MCP fallback documented below is OPT-IN, not a skill — enable manually via
agentic-qa-core/references/mcp-atlassian-optin.md.
Expected matches: typically none. Repo-specific composability (which workflow skills load this) lives in <repo-core>/references/acli-integration.md §Composability.
Skip step if the catalog is unavailable; log skill_resolution: "fallback-inline" plus missing: [<categories>] per the strategy doc's composability fallback contract.
Fallback: Atlassian MCP
Opt-in only: this MCP is NOT enabled in the default boilerplate. To use it, add the atlassian block from
agentic-qa-core/references/mcp-atlassian-optin.mdto.mcp.json,opencode.jsonc,.codex/config.tomlAND.pi/mcp.json(parity is checked), ensureATLASSIAN_*in.envare set, and restart the agent. Behavior below applies only after opt-in.
If acli is not installed or authenticated, fall back to the Atlassian MCP server (MCP tool namespace: mcp__atlassian__* or similar — check the MCP tool list for the exact prefix in the current environment).
When to prefer MCP over acli:
aclibinary is not installed in the environment.acliauth fails and cannot be fixed in the current session.- The operation is one of the documented
acliblind spots: enumerate custom fields, edit custom-field values on existing work items, manage workflows / issue types / priorities / resolutions / project versions / components, upload attachments, add watchers, add an item to a sprint.
When to prefer acli over MCP:
- Bulk operations (acli consumes far fewer tokens per call).
- Scripting / CI pipelines.
- Operations that return large result sets (MCP payloads inflate token usage).
Coverage parity: MCP and acli overlap for issues, projects, boards, sprints, comments, and basic Confluence ops. For org-admin user lifecycle and Confluence space CRUD, acli is more direct. For schema/admin reads (field catalog, workflow definitions), MCP/REST is the only viable path.
Command structure
acli <product> [<feature>] <action> [flags]| Product | Purpose |
jira | Jira Cloud — work items, projects, boards, sprints, filters, dashboards, custom-field definitions |
confluence | Confluence Cloud — spaces (CRUD), blog posts, page view |
admin | Organization admin — API-key auth, user lifecycle |
auth | Global OAuth (cross-product, newer top-level surface) |
rovodev | Rovo Dev AI coding agent (separate beta product) |
feedback | Send feedback or a bug report to Atlassian |
config | Atlassian Government Cloud configuration (gov-cloud) |
completion | Generate shell-autocompletion script (bash / zsh / fish / powershell) |
Every level has --help. Use it aggressively when unsure:
acli --help
acli jira --help
acli jira workitem --help
acli jira workitem create --helpQuick start
# 1. Authenticate against a site using an API token (scriptable path)
echo "$ATLASSIAN_API_TOKEN" | acli jira auth login \
--site "<your-site>.atlassian.net" \
--email "you@example.com" \
--token
# 2. Verify
acli jira auth status
# 3. Create a work item
acli jira workitem create --project "{{PROJECT_KEY}}" --type "Task" --summary "Draft the Q3 OKRs"
# 4. Search with JQL — ALWAYS pass --paginate or --limit explicitly
acli jira workitem search --jql "project = {{PROJECT_KEY}} AND status = 'To Do'" --paginate --json
# 5. Transition one or many
acli jira workitem transition --jql "project = {{PROJECT_KEY}} AND assignee = currentUser()" \
--status "In Progress" --yes --ignore-errorsRepo-specific quick start: when the host repo defines its own workflow (status names, project keys, slug-resolved custom fields), see
<repo-core>/references/acli-integration.md— it documents the project-flavored variant of the steps above.
Top-level command map
Jira (acli jira)
| Subcommand | What it covers |
auth | login · logout · status · switch — API-token or OAuth |
workitem | archive · assign · attachment (list / delete) · clone · comment (create / delete / list / update / visibility) · create · create-bulk · delete · edit · link (create / delete / list / type) · search · transition · unarchive · view · watcher (list / remove) |
project | archive · create · delete · list · restore · update · view |
board | create · delete · get · list-projects · list-sprints · search |
sprint | create · delete · list-workitems · update · view |
filter | add-favourite · change-owner · get · get-columns · list · reset-columns · search · update |
dashboard | search |
field | cancel-delete · create · delete · update — custom-field DEFINITIONS only, NOT values, and no listing |
Confluence (acli confluence)
| Subcommand | What it covers |
auth | login · logout · status · switch — same model as jira auth |
space | archive · create · list · restore · update · view (full CRUD) |
blog | create · list · view |
page | view (read-only: page CRUD is not exposed; confirm with acli confluence page --help) |
Admin (acli admin)
| Subcommand | What it covers |
auth | login · logout · status · switch — API key |
user | activate · deactivate · delete · cancel-delete |
The selector pattern (the thing to internalize)
Most mutating workitem commands (edit, transition, assign, archive, clone, comment create) accept one of these target selectors:
| Selector | When to use |
--key KEY-1,KEY-2 | You already know the exact keys |
--jql "..." | You want everything matching a JQL query |
--filter 10001 | You want to reuse a saved Jira filter |
--from-file f | You have a file listing keys (archive/unarchive/assign) |
When the selector matches many items, the command is a batch operation. Two flags almost always matter:
-y, --yes— skip the interactive confirmation prompt. Required in CI; if omitted the command hangs waiting on stdin. Note: this flag does NOT exist onadmin user delete/admin user cancel-delete(use--ignore-errorsthere instead).--ignore-errors— do not abort the batch when a single item fails.
Output and piping
All list/search/view commands support three shapes:
- default table (human-readable)
--json(forjq/ scripts)--csv(spreadsheet-friendly)
Example pipe patterns:
# Count only
acli jira workitem search --jql "project = {{PROJECT_KEY}}" --count
# Save full result set to CSV
acli jira workitem search --jql "project = {{PROJECT_KEY}}" --paginate --csv > team.csv
# Extract a single field with jq
acli jira workitem view {{PROJECT_KEY}}-123 --json | jq '.fields.summary'The JSON shape from workitem search has a top-level issues array (not workitems) — the Jira REST v3 wire format shows through.
Publishing rich text (the default workflow)
Jira stores rich-text content (descriptions, comments, and any rich-text field) as ADF — Atlassian Document Format, a JSON tree of typed nodes (heading, paragraph, bulletList, orderedList, codeBlock, blockquote, rule, table, panel, expand) with inline marks (strong, em, code, link, strike).
acli accepts ADF JSON in every rich-text input. acli never converts markdown — passing # Heading to --description or --body stores the literal string # Heading wrapped in a single ADF paragraph.
⚠️ Asymmetry:
createsupports custom-field rich text,editdoes NOT.acli workitem create --from-jsonaccepts custom fields viaadditionalAttributes(ADF doc payloads work).acli workitem edit --from-jsonhard-rejects every custom-field shape (additionalAttributes,fields, flatcustomfield_X) with exit 1 +unknown fielderror. No silent drop, no escape hatch in the binary. To update or correct a rich-text custom field on an existing work item, you MUST use the REST PUT workaround documented below —aclicannot do it.
To publish anything richer than plain prose, use this three-step workflow by default:
1. Author the content in Markdown.
2. Convert MD → ADF JSON using scripts/md-to-adf.ts.
3. Pass the ADF JSON to the matching acli flag — or, for cases acli cannot cover, into a REST body.The bundled converter
Location: .agents/skills/acli/scripts/md-to-adf.ts. Runtime: Bun.
CLI usage:
bun .agents/skills/acli/scripts/md-to-adf.ts input.md output.adf.json
# stdin form
cat input.md | bun .agents/skills/acli/scripts/md-to-adf.ts - output.adf.json
# stdout form (omit output arg)
bun .agents/skills/acli/scripts/md-to-adf.ts input.md > output.adf.jsonProgrammatic usage (when batching across many fields or many work items in one script):
import { mdToAdf, validateAdf } from "./.agents/skills/acli/scripts/md-to-adf.ts";
const adf = mdToAdf(markdownString); // returns { type: "doc", version: 1, content: [...] }
const { valid, errors } = validateAdf(adf); // gate ANY ADF before publishingCovered markdown subset: headings 1–6, bullet lists, ordered lists, nested lists (indentation-based), GFM tables (| a | b | + |---|---| separator), panels (GitHub-alert blockquotes), expand blocks (<details><summary>), Jira-native emoji (:short_name:), status lozenges ({status:color|TEXT}), mentions (@[Name](accountId)), fenced code blocks (with optional language tag), inline code, bold, italic (snake_case-safe), strikethrough, links, blockquotes, horizontal rule, paragraphs.
Rich-block syntax cheat-sheet:
| Markdown you write | ADF node produced |
| H1 | H2 | then | --- | --- | then body rows | table (header row → tableHeader, body → tableCell; inline marks work inside cells; | escapes a literal pipe) |
> [!NOTE] / [!INFO] (blue) · [!TIP] / [!SUCCESS] (green) · [!IMPORTANT] (purple) · [!WARNING] (yellow) · [!CAUTION] / [!ERROR] (red), then > body lines | panel with panelType info / success / note / warning / error. Body re-parsed as Markdown (can hold lists, code, etc.) |
| Two-space (or deeper) indentation under a list item | nested bulletList / orderedList inside that listItem; depth = indent width; bullet/ordered mix per level |
<details> / <summary>Title</summary> / body / </details> | expand with attrs.title; body re-parsed as Markdown |
:white_check_mark: :x: :warning: … any :short_name: | emoji node (Jira resolves the shortName; curated status marks also carry a Unicode text fallback). Inline code is parsed first, so a colon inside `code` is safe |
{status:green|DONE} (colors: neutral purple blue red yellow green) | status node — the coloured lozenge/pill for transition states. localId not required (Jira injects none on publish) |
@[Display Name](accountId) | mention node. The accountId is supplied explicitly (resolve it via /rest/api/3/user/search — see references/adf-authoring-style.md §mentions); a bare @name is NOT converted |
Media (images / videos) are NOT Markdown —  does not work, because an ADF media node needs the opaque media-services UUID of an uploaded file. Use the bundled helper scripts/jira-attach-media.ts instead (upload → resolve UUID → emit/publish the mediaSingle > media node). Example: bun .agents/skills/acli/scripts/jira-attach-media.ts BUG-123 ./repro.png --caption "Repro step 3" --publish. Full recipe + when-to-use in references/adf-authoring-style.md §media.
Out of scope (extend the converter if your project needs them): nestedExpand (expand inside a table cell).
This section covers HOW Markdown becomes ADF. For WHEN to reach for a table vs a panel vs a nested list — i.e. how to make field content visually scannable instead of flat prose — see
references/adf-authoring-style.md. Workflow skills cite that file at each point they fill a Jira rich-text field.
Validation gate (fail fast before Jira)
The converter validates its output by default against an embedded ADF allowlist, then refuses to write and exits non-zero if the document is invalid. This turns an opaque Jira HTTP 400 INVALID_INPUT at publish time into a node-level diagnostic at author time. The gate is zero-dependency — it does NOT use @atlaskit/adf-utils (that package transitively pulls ProseMirror + Statsig and breaks the converter's zero-dep contract). The rules are inlined in md-to-adf.ts.
What it catches: unknown node types, unknown / invalid marks, code co-occurring with strong/em/strike/underline/subsup/textColor (the HTTP 400 combined-marks bug), heading level outside 1–6, missing link href, empty text nodes, illegal containment (e.g. a paragraph directly under a bulletList), and a malformed root (type ≠ doc or version ≠ 1).
# validate is on by default during conversion; bypass with --no-validate
bun .agents/skills/acli/scripts/md-to-adf.ts input.md out.adf.json --no-validate
# gate an ALREADY-assembled ADF doc (jq create payload field, or a REST PUT body)
bun .agents/skills/acli/scripts/md-to-adf.ts --check field.adf.json # exit 0 valid, 1 invalidRecommended habit: after splicing ADF into a --from-json create payload or a REST PUT body (where the wrapper is assembled outside the converter), run --check on each ADF field before sending. The gate is necessary but not sufficient — a round-trip GET of the field after write is still the only way to catch server-side coercion (Jira silently drops some invalid nodes).
Size budget (Jira counts the serialized ADF, not the text)
Jira Cloud caps every rich-text value (description, comment, rich-text custom field) at 32,767 characters, and the cap is not configurable on Cloud. What it counts is the serialized ADF JSON of the value, not the visible text: every node, mark and attribute is paid for. ADF is several times longer than the Markdown it came from, and structure-heavy content (tables, nested lists, panels, code blocks) expands the most. The measurements behind this paragraph are in .context/ADR/ADR-0006-forensic-measurements-ledger.md.
So every write of a rich-text value measures the FULL value as it will be stored, before sending it:
bun .agents/skills/acli/scripts/md-to-adf.ts body.md body.adf.json
jq -c . body.adf.json | wc -m # must stay at or under 30000The budget is 30,000, which leaves room under the cap for text a human adds to the same field later. When the field already holds content you keep (a section rewrite inside a longer description), measure the merged document, not only your part.
Over budget → STOP before writing. Propose which sections move out of this field and where (the owning workflow names the destinations), with the size each move saves, and wait for the user's decision. A Jira rejection for length (CONTENT_LIMIT_EXCEEDED on REST v3, or a 400 naming the field length) is the same STOP. Never truncate, never split one value across two fields or two comments, never drop the formatting to squeeze under the cap.
Recipe by Jira surface
| Surface | How to publish ADF | Notes |
description on workitem create | --from-json payload, description key holds an ADF doc | Custom-field values live in additionalAttributes of the same payload, same ADF shape |
description on workitem edit | --description-file <file> accepts a JSON file containing an ADF doc | acli auto-detects ADF vs plain text by file content |
Rich-text custom field on workitem create | additionalAttributes.customfield_NNNNN = ADF doc inside --from-json | Same shape as description |
| Rich-text custom field on an existing item | acli cannot do this — use REST PUT workaround. PUT /rest/api/3/issue/{KEY} with {"fields": {customfield_NNNNN: <ADF>}} via curl | acli workitem edit hard-rejects additionalAttributes, fields, and flat customfield_X with ✗ Error: json: unknown field …. Confirmed empirically. See gotcha #4 + dedicated workaround section below. |
| Comment create | comment create --body-file <file> (alias -F) accepts ADF | The --body (plain) flag remains plain text only |
| Comment update | comment update --body-adf <file> | Dedicated ADF flag |
Worked end-to-end example
# 1. Author each rich-text field as Markdown
cat > /tmp/desc.md <<'MD'
## User Story
- As a user
- I want X
- So that Y
## Context
Some context paragraph with **bold** and `inline_code`.
MD
cat > /tmp/ac.md <<'MD'
## Scenario: happy path
Given a valid input
When the user submits
Then the response is 200 OK
MD
# 2. Convert each MD file to ADF JSON
bun .agents/skills/acli/scripts/md-to-adf.ts /tmp/desc.md /tmp/desc.adf.json
bun .agents/skills/acli/scripts/md-to-adf.ts /tmp/ac.md /tmp/ac.adf.json
# 3. Splice the ADF docs into the create-from-json payload
jq -n \
--arg pk "{{PROJECT_KEY}}" \
--slurpfile desc /tmp/desc.adf.json \
--slurpfile ac /tmp/ac.adf.json \
'{
projectKey: $pk,
type: "Story",
summary: "Example summary",
description: $desc[0],
labels: ["example"],
additionalAttributes: {
customfield_NNNNN: $ac[0]
}
}' > /tmp/story.json
# 4. Submit
acli jira workitem create --from-json /tmp/story.json --jsonBatch pattern (many work items, many rich fields)
When the task is to populate N work items with M rich-text fields each, the converter scales linearly with negligible overhead. Recommended pattern:
- Write one generator script (
generate.ts) that holds the per-field Markdown content for every item as inline string literals. - The script imports
mdToAdfand converts every field in-process — no shell hop per conversion. - The script writes one
create --from-jsonpayload per item (/tmp/item-N.json). - A shell loop runs
acli jira workitem create --from-json /tmp/item-N.json --jsonper file, capturing the new key from stdout. - For comments, follow the same approach: write the comment Markdown inline, convert in-process, post with
acli jira workitem comment create -k <KEY> -F /tmp/comment-N.adf.json.
This pattern scales cleanly to dozens of items in one run. The bottleneck is authoring quality, not the conversion mechanic.
WORKAROUND: Editing rich-text custom fields on existing work items (REST PUT)
This is the only working path: there is no acli-native channel for editing custom-field values on existing items. The recipe below is the turnkey workaround.
Prerequisites. Two variables set in .env (or in the secret manager the varlock schema names). Nothing is exported into your shell: each curl below runs inside the .env loader, bunx varlock run --filter <names> -- sh -c '...', which hands the two values to that one child process and to nothing else:
ATLASSIAN_EMAIL— the API-token owner's emailATLASSIAN_API_TOKEN— the API token paired with the email
The site host is not an env var. It lives in .agents/project.yaml ->
issue_tracker.atlassian_url, and the recipes below read it with
$(bun run --silent jira:url). A copy in .env goes stale, and one inherited
from the parent shell silently shadows the file. Never reintroduce ATLASSIAN_URL as a shell
variable in a recipe — resolve the host, do not interpolate it.
Recipe.
# 1. Author the new value as Markdown
cat > /tmp/new.md <<'MD'
## New content
- with **bold**, `inline code`, and a [link](https://example.com)
MD
# 2. Convert MD → ADF
bun .agents/skills/acli/scripts/md-to-adf.ts /tmp/new.md /tmp/new.adf.json
# 3. Wrap the ADF doc in the REST `{ "fields": { ... } }` envelope
# (NOTE: same ADF payload acli would consume; only the wrapper key changes)
jq -n --slurpfile adf /tmp/new.adf.json \
'{fields: {customfield_NNNNN: $adf[0]}}' > /tmp/put.json
# 4. PUT against the issue, credentials loaded for this one process only
bunx varlock run --filter ATLASSIAN_EMAIL,ATLASSIAN_API_TOKEN -- sh -c '
curl -sS -w "\nHTTP %{http_code}\n" \
-u "$ATLASSIAN_EMAIL:$ATLASSIAN_API_TOKEN" \
-X PUT "$(bun run --silent jira:url)/rest/api/3/issue/{{PROJECT_KEY}}-123" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
--data-binary @/tmp/put.json'
# Expected: HTTP 204 (Jira returns no body on a successful PUT)Every other REST recipe in this skill (references/gotchas.md, references/workitem.md, references/adf-authoring-style.md) that names $ATLASSIAN_EMAIL / $ATLASSIAN_API_TOKEN runs the same way: wrap the command in bunx varlock run --filter ATLASSIAN_EMAIL,ATLASSIAN_API_TOKEN -- sh -c '...' (double quotes inside), never export them or source .env first.
Reference. Official Atlassian REST v3 PUT endpoint: https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-issueidorkey-put
Empirical proof this is the only path. Three variants tested against acli workitem edit --from-json on a real workitem:
Payload shape sent to acli edit | Result |
{issues:[...], additionalAttributes:{customfield_X:<ADF>}} | ✗ Error: json: unknown field "additionalAttributes" · exit 1 |
{issues:[...], fields:{customfield_X:<ADF>}} | ✗ Error: json: unknown field "fields" · exit 1 |
{issues:[...], customfield_X:<ADF>} | ✗ Error: json: unknown field "customfield_X" · exit 1 |
Same ADF doc through REST PUT: HTTP 204 OK.
Batch variant. Loop the recipe per --data-binary @/tmp/put-N.json and capture HTTP codes:
bunx varlock run --filter ATLASSIAN_EMAIL,ATLASSIAN_API_TOKEN -- sh -c '
host=$(bun run --silent jira:url)
for KEY in {{PROJECT_KEY}}-1 {{PROJECT_KEY}}-2 {{PROJECT_KEY}}-3; do
status=$(curl -sS -o /dev/null -w "%{http_code}" \
-u "$ATLASSIAN_EMAIL:$ATLASSIAN_API_TOKEN" \
-X PUT "$host/rest/api/3/issue/$KEY" \
-H "Content-Type: application/json" \
--data-binary @/tmp/put-"$KEY".json)
echo "$KEY -> HTTP $status"
done'When this becomes unnecessary. If Atlassian adds an additionalAttributes-style channel to acli workitem edit, retire this workaround and update the recipe table.
Why this is the default
- Authoring in Markdown is fast, reviewable in pull requests, diffable.
- The conversion is deterministic — the same Markdown always produces the same ADF tree.
- One workflow covers every rich-text surface uniformly: descriptions, comments, custom fields, all the same three steps.
- Identifier-heavy prose (snake_case, kebab-case) survives the conversion because the italic detection has word-boundary guards.
Anti-patterns — NEVER do these (tool-level)
These are tool-level anti-patterns intrinsic to the acli binary and its REST companion. They apply regardless of host repo. Gotchas describe surprising behavior to remember; anti-patterns describe actions to refuse outright. Both apply.
- T1. NEVER hand-author raw ADF JSON for descriptions, comments, or rich-text custom fields. Use
scripts/md-to-adf.ts— deterministic, diffable, snake_case-safe, and avoids the combined-marks bug (inlinecodeco-occurring withstrong/emcauses HTTP 400). - T2. NEVER hardcode Jira
customfield_NNNNNIDs in scripts or AI output that consumesacli. Resolve via the host project's slug catalog (see the host repo'sacli-integration.md). IDs differ per workspace; slugs travel. - T3. NEVER assume
acliaccepts custom-field input onworkitem edit. It hard-rejects every shape (additionalAttributes,fields, flatcustomfield_X) with exit 1. Use the RESTPUT /rest/api/3/issue/{KEY}workaround documented above — there is no acli-native path. - T4. NEVER run a bulk
aclimutation (transition, edit, comment, link, archive) without first verifyingacli jira auth status. Silent auth expiry cascades into HTTP 401s mid-loop, leaving the batch half-applied with no clean rollback. - T5. NEVER write a rich-text value without measuring its serialized ADF against the 30,000 budget (
jq -c . <file>.adf.json | wc -m). Jira's cap counts the ADF JSON, which is several times the Markdown length, so a plan that "looks short" is still rejected. Over budget → STOP and propose which sections move where; never truncate, never split one value across two fields.
Repo-specific anti-patterns (workflow abstraction, project-key portability, TMS modality boundaries, prod-workspace safety, CI batching, version pinning, sync-script auth) live in
<repo-core>/references/acli-integration.md. Load it whenever a session touches the host repo's Jira workflow.
Seven gotchas to keep in mind always
--paginateis opt-in. Default limit is server-side (30–50 depending on command). No warning on truncation. If you are counting, iterating, or making decisions based on the result, pass--paginate.- Custom fields on
workitem creatego throughadditionalAttributesin--from-json. Numeric IDs only (customfield_NNNN), no name-addressing. Documented value shapes in thecreatetemplate are:{"value": "..."}(single-select), bare number, bare string.workitem editactively REJECTS custom-field input — hard error, exit 1, not a silent drop (empirically confirmed acrossadditionalAttributes,fields, and flatcustomfield_Xshapes). For editing custom-field values on existing items, the only working path is RESTPUT /rest/api/3/issue/{KEY}viacurlusing the session env vars — see the "WORKAROUND" subsection in "Publishing rich text" above, plusreferences/gotchas.md§4 andreferences/workitem.md. aclicannot enumerate custom fields.acli jira fieldonly does create/update/delete/cancel-delete. To discover field IDs, useworkitem view --json | jqagainst an item that has the field set, or callGET /rest/api/3/fielddirectly. There is no in-CLI listing. Host repos typically cache the catalog under.agents/and resolve fields by slug — see<repo-core>/references/acli-integration.md.- Transitions match by status name, not transition ID. When two transitions lead to the same status with different validators, the CLI picks one and may fail. No
--transition-idescape hatch exists — fall back to REST if this hits. - Trace IDs are the only debug signal. An
unexpected error, trace id: XXXXXXXXline is all you get on backend failures. Capture and log the trace ID always; Atlassian Support needs it. workitem link createflag names are misleading —--outand--inare EMPIRICALLY INVERTED relative to Jira's outward/inward semantics. Runningacli jira workitem link create --out X --in Y --type Dependenciesproduces "Y depends on X" — NOT "X depends on Y" as the flag names suggest. Y becomes the outward party (the one that performs the outward verb, e.g. "depends on" / "blocks" / "causes"); X becomes the inward party. Confirmed empirically against Dependencies; the same inversion applies to ALL outward-asymmetric link types (Blocks, Blocking, Causes, Duplicate, Cloners, Defect, Test, Test Automation, Test Design, Test Execute). Symmetric types (Relates) are immune — direction is lost either way. Reverse-mapping rule of thumb:--outtakes the PREREQUISITE (the inward partner in Jira's UI);--intakes the DEPENDENT (the outward partner in Jira's UI). Mandatory verification after every link create: runacli jira workitem link list --key <expected-dependent> --jsonand confirm the response showsoutwardIssueKey: <expected-prerequisite>. If the direction is wrong, delete the link and recreate with swapped flags — delete first: Jira dedupes a link between the same pair and type regardless of direction, so adding the corrected link on top of the wrong one is a silent no-op. Deep recipe + per-type mapping table →references/workitem.md.- The vendor's own
--helpexamples are sometimes stale, and they fail exactly as a typo would.acli jira workitem comment create --helpprints its examples without thecreatesubcommand (acli jira workitem comment --key "KEY-1" --body "..."), which exits non-zero withunknown flag: --keybecause the flags live oncreate. An agent copying the vendor example loses a round trip and, worse, may conclude the command does not exist. Trust the forms inreferences/workitem.mdover the binary's examples; two other fields document narrower behaviour than they have (parentIssueIddescribes itself as sub-task-only and parents to an Epic fine). Also note what is NOT there:workitem edithas no components flag at all.
Top-level utilities
Quick-reference for the top-level surface that doesn't fit under a product. None of these need a separate reference file — they're documented here in full.
acli completion — shell autocompletion
acli completion bash > /etc/bash_completion.d/acli
acli completion zsh > "${fpath[1]}/_acli"
acli completion fish > ~/.config/fish/completions/acli.fish
acli completion powershell > acli.ps1Each subcommand prints a shell script to stdout. Pipe to the location your shell expects (above are the conventional paths).
acli feedback — report a problem to Atlassian
acli feedback \
--summary "JSON shape on edit --generate-json is misleading" \
--details "The template doesn't include additionalAttributes for custom fields..." \
--email "you@example.com" \
--time "1h" \
--attachments error.log,trace.txtFlags: -s, --summary (required-ish), -d, --details (required-ish), -e, --email, -t, --time (estimated timeframe like 1h, 15m), -a, --attachments (multiple files).
acli auth — global OAuth (newer surface)
A top-level OAuth login that authenticates across products in one step. Distinct from per-product jira auth / admin auth / confluence auth. Use the per-product login for token-based CI; use the global one for interactive multi-product browsing.
acli auth login # interactive OAuth
acli auth status
acli auth switch
acli auth logoutSee references/auth.md for the full auth model.
acli config gov-cloud — Atlassian Government Cloud
acli config gov-cloud --enable
acli config gov-cloud --statusNiche — only relevant if your org is on Atlassian Government Cloud. Not used in standard commercial Jira/Confluence.
Navigation — when to load which reference
Load the reference that matches the user's current need. Do not preload all of them.
| If the user wants to… | Load |
| Log in, switch sites, handle tokens, authenticate in CI | references/auth.md |
| Work with Jira tickets (create, edit, transition, search, bulk, comments, links, watchers, custom-field shapes) | references/workitem.md |
| Manage projects, boards, sprints, filters, dashboards, custom-field definitions | references/project-board-sprint.md |
| Work with Confluence spaces, blogs, pages | references/confluence.md |
| Run org-level admin tasks (API key, user lifecycle) | references/admin.md |
| Pipe output, produce JSON/CSV, dry-run, run on CI/CD | references/output-and-automation.md |
| Diagnose surprising behavior, known bugs, REST fallback points | references/gotchas.md |
| Publish rich text to descriptions, comments, or custom fields | Inline section "Publishing rich text" + scripts/md-to-adf.ts |
| Make Jira field content visually excellent (when to use tables / panels / nested lists for readability) | references/adf-authoring-style.md |
Plug acli into the host repo's workflow (TMS modality, slug catalog, project conventions, anti-patterns specific to this repo) | <repo-core>/references/acli-integration.md |
Working style
- Default to Markdown authoring for any rich-text field. Never pass raw markdown to
--description,--body, or any custom-field value —aclidoes not convert markdown. Usescripts/md-to-adf.tsto produce ADF, then pass the JSON. See "Publishing rich text" above. - Prefer API-token auth in scripted contexts.
--web/ OAuth is for humans at a terminal. - Always pass
--yesin CI for any mutating command (where the flag exists). - Always pass
--paginatewhen a downstream script consumes the result. - Scaffold complex payloads with
--generate-json(create, edit, project create, project update, link create, create-bulk). Pipe to a file, edit, submit with--from-json. Note:--generate-jsonis static — it does NOT introspect the actual project schema, so for custom-field shapes you may need to view a real item. - Capture the trace ID on any failure and surface it when reporting to the user.
- Do not invent flags. When unsure, run
acli <path> --help— it is authoritative and version-pinned to the installed binary. Convention: every multi-word flag is kebab-case (--from-json,--searcher-key,--filter-id,--order-by). camelCase variants will fail. - Verify subcommand existence before assuming. Unknown subcommands silently fall back to parent help with exit 0 — they do NOT error. Read the help body, don't trust the exit code.
Know what
aclicannot do. All of the following require REST or MCP —aclidoes not cover them (confirm against the installed binary withacli <path> --help):- Enumerate custom fields (
fieldhas nolist). - Edit custom-field values on existing work items (
workitem editdoes not document custom-field input). - Manage workflows, workflow schemes, statuses, or transition definitions.
- Manage issue types, priorities, resolutions, project versions, project components.
- Add a work item to a sprint (Atlassian tracked it as
JRACLOUD-97107when this was written). - Upload attachments, add watchers.
- Retrieve the cached auth token for reuse in another tool.
- Bitbucket operations (out of scope entirely).
- Confluence page CRUD beyond
page view(space and blog have a fuller CRUD surface; seereferences/confluence.md).
See
references/gotchas.mdfor the full list with REST recipes.- Enumerate custom fields (
Installation (reference only)
Users usually already have acli installed. If not, point them at:
- Official guide: https://developer.atlassian.com/cloud/acli/guides/install-acli/
- macOS:
brew tap atlassian/homebrew-acli && brew install acli - Linux (Debian/Ubuntu):
apt install acli(after adding the Atlassian apt repo) - Linux (RHEL/Fedora):
yum install acli(after adding the Atlassian yum repo) - Windows: PowerShell
curlinstall (no Chocolatey/MSI yet) - CI one-liner (Linux):
curl -LO "https://acli.atlassian.com/linux/1.3.18/acli_linux_amd64/acli" && chmod +x acli
Pin to a version URL in production pipelines — latest/ has caused same-day mass failures. Each release has a support window; check the vendor policy. Run acli --version to check.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

