Atlassian CLI (acli) Quick Reference

Common acli commands for Jira operations used across this project's workflows.

Prerequisites

• acli must be installed and authenticated: acli jira auth login --web
• Check auth status: acli jira auth status

Installed version:

!acli --version || true

If the output above says the version is outdated, tell the user before running any other command.

Key Flag for Subcommands

The view command accepts the issue key as a positional argument, but subcommands like comment list, comment create, transition, edit, etc. require the --key flag:

acli jira workitem view PROJ-123                          # positional OK
acli jira workitem comment list --key PROJ-123            # --key required
acli jira workitem comment create --key PROJ-123 --body-file comment.json  # --key required

Always Use ADF

Always write comment bodies and issue descriptions in Atlassian Document Format (ADF). Plain text loses all formatting, and markdown or wiki markup renders as literal characters.

Write the ADF to a JSON file and pass the file path, since inline JSON breaks easily under shell quoting. See ADF Formatting for the node structure.

View Issue Details

acli jira workitem view PROJ-123

With all fields (description, comments, etc.):

acli jira workitem view PROJ-123 --fields "*all"

JSON output for parsing:

acli jira workitem view PROJ-123 --json

Specific fields only:

acli jira workitem view PROJ-123 --fields "summary,status,priority,description,comment"

Search Issues with JQL

acli jira workitem search --jql 'summary ~ "CVE-2024-1234" AND summary ~ "repo-name"' --json

Search by text across all fields:

acli jira workitem search --jql 'text ~ "search terms" AND key != PROJ-123' --json

Search by component:

acli jira workitem search --jql 'component = "my-component" AND key != PROJ-123' --json

Search recently resolved issues:

acli jira workitem search --jql 'text ~ "search terms" AND status in (Resolved, Done, Closed) AND resolved >= -30d' --json

Limit results and select fields:

acli jira workitem search --jql 'project = PROJ' --fields "key,summary,status" --limit 20 --json

Add Comment to Issue

Write the comment as an ADF document in comment.json:

{
  "type": "doc",
  "version": 1,
  "content": [
    {
      "type": "paragraph",
      "content": [{"type": "text", "text": "Comment text here"}]
    }
  ]
}

Then post it:

acli jira workitem comment create --key PROJ-123 --body-file comment.json

Update an existing comment with --body-adf, since comment update --body-file only takes plain text:

acli jira workitem comment update --key PROJ-123 --id 10001 --body-adf comment.json

List Comments on Issue

acli jira workitem comment list --key PROJ-123 --json

Use view to see the raw ADF, since comment list flattens bodies to plain text and drops list items:

acli jira workitem view PROJ-123 --fields "comment" --json

Transition Issue Status

First check available transitions:

acli jira workitem view PROJ-123 --fields "status" --json

Then transition:

acli jira workitem transition --key PROJ-123 --status "Done"
acli jira workitem transition --key PROJ-123 --status "In Progress"
acli jira workitem transition --key PROJ-123 --status "Resolved"

Create Issue

Write the issue definition in workitem.json with an ADF description. The assignee and labels fields are optional.

{
  "projectKey": "PROJ",
  "type": "Bug",
  "summary": "Bug title",
  "assignee": "[email protected]",
  "labels": ["bug", "triage"],
  "description": {
    "type": "doc",
    "version": 1,
    "content": [
      {
        "type": "paragraph",
        "content": [{"type": "text", "text": "Description"}]
      }
    ]
  }
}

Then create it:

acli jira workitem create --from-json workitem.json

Edit Issue

acli jira workitem edit --key PROJ-123 --summary "Updated summary"
acli jira workitem edit --key PROJ-123 --assignee "@me"

ADF Formatting

ADF is the JSON format Jira uses for rich text with headings, code blocks, lists, etc. The root is always a doc node with "version": 1.

Generate a sample JSON template:

acli jira workitem create --generate-json
acli jira workitem edit --generate-json

Editing with ADF

Write a JSON file with issues and description fields:

{
  "issues": ["PROJ-123"],
  "description": {
    "type": "doc",
    "version": 1,
    "content": [
      {
        "type": "heading",
        "attrs": {"level": 2},
        "content": [{"type": "text", "text": "Section Title"}]
      },
      {
        "type": "paragraph",
        "content": [
          {"type": "text", "text": "Normal text and "},
          {"type": "text", "text": "inline code", "marks": [{"type": "code"}]},
          {"type": "text", "text": " in a paragraph."}
        ]
      },
      {
        "type": "codeBlock",
        "attrs": {"language": "json"},
        "content": [{"type": "text", "text": "{\"key\": \"value\"}"}]
      },
      {
        "type": "bulletList",
        "content": [
          {"type": "listItem", "content": [{"type": "paragraph", "content": [{"type": "text", "text": "Bullet item"}]}]}
        ]
      },
      {
        "type": "orderedList",
        "content": [
          {"type": "listItem", "content": [{"type": "paragraph", "content": [{"type": "text", "text": "Numbered item"}]}]}
        ]
      }
    ]
  }
}

Then apply:

acli jira workitem edit --from-json workitem.json --yes

ADF Node Reference

Known Limitations

• Markdown and wiki markup are never rendered, they appear as literal text
• comment update accepts ADF only through --body-adf, its --body-file flag is plain text

List Projects

acli jira project list