acli

name	acli
description	Use Atlassian CLI (acli) to manage Jira work items, projects, and workflows from the command line. Ideal for bulk operations, automation, scripting, and when users request CLI-based Jira interactions. Trigger on requests like "use Jira CLI", "create Jira issues via CLI", "bulk update Jira tickets", "automate Jira workflows", or when users want to script Jira operations.

Atlassian CLI for Jira

Overview

Atlassian CLI (acli) is the official command-line interface for Jira Cloud that enables management of work items, projects, and workflows directly from the terminal. Use this skill when:

• Users request CLI-based Jira operations
• Bulk operations are needed (updating multiple issues, bulk transitions)
• Automation or scripting is required
• Users want to avoid the Jira UI for repetitive tasks

Authentication

Before using any Jira commands, authenticate using OAuth:

# Interactive OAuth login (recommended)
acli jira auth login --web

# Login with API token (for automation)
echo <token> | acli jira auth login --site "mysite.atlassian.net" --email "[e-mail]" --token

Work Item Commands

Work items (issues/tickets) are the core of Jira. The CLI uses "workitem" instead of "issue".

Create Work Items

# Basic creation
acli jira workitem create --summary "Fix login bug" --project "PROJ" --type "Bug"

# With additional fields
acli jira workitem create \
  --summary "Add new feature" \
  --project "PROJ" \
  --type "Story" \
  --assignee "[e-mail]" \
  --label "frontend,priority" \
  --description "Detailed description here"

# From file content
acli jira workitem create --from-file "description.txt" --project "PROJ" --type "Task"

# From JSON (for complex work items)
acli jira workitem create --generate-json  # Generate template
acli jira workitem create --from-json "workitem.json"

# With ADF description (rich formatting)
acli jira workitem create \
  --summary "Implement user authentication" \
  --project "PROJ" \
  --type "Story" \
  --description '{
    "version": 1,
    "type": "doc",
    "content": [
      {
        "type": "paragraph",
        "content": [
          {"type": "text", "text": "Implement secure user authentication with the following requirements:", "marks": [{"type": "strong"}]}
        ]
      },
      {
        "type": "bulletList",
        "content": [
          {
            "type": "listItem",
            "content": [
              {
                "type": "paragraph",
                "content": [
                  {"type": "text", "text": "OAuth 2.0 support"}
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "content": [
              {
                "type": "paragraph",
                "content": [
                  {"type": "text", "text": "JWT token management"}
                ]
              }
            ]
          }
        ]
      }
    ]
  }'

# ADF description from file
acli jira workitem create \
  --summary "Database migration" \
  --project "PROJ" \
  --type "Task" \
  --description-file "description.adf.json"

Key flags:

• --summary (required): Work item title
• --project (required): Project key (e.g., "TEAM", "PROJ")
• --type (required): Work item type ("Task", "Bug", "Story", "Epic")
• --assignee: Email or account ID, use '@me' for self-assignment
• --label: Comma-separated labels
• --description: Plain text or Atlassian Document Format (ADF)
• --description-file: Read description from file (plain text or ADF)

View Work Items

# View single work item
acli jira workitem view KEY-123

# View as JSON
acli jira workitem view KEY-123 --json

# View specific fields only
acli jira workitem view KEY-123 --fields summary,status,assignee,comment

# Open in browser
acli jira workitem view KEY-123 --web

Search Work Items

Use JQL (Jira Query Language) to search:

# Basic search
acli jira workitem search --jql "project = TEAM"

# Complex search with pagination
acli jira workitem search --jql "project = TEAM AND status = 'In Progress'" --paginate

# Get count only
acli jira workitem search --jql "assignee = currentUser()" --count

# Export to CSV with specific fields
acli jira workitem search \
  --jql "project = TEAM" \
  --fields "key,summary,status,assignee" \
  --csv

Common JQL patterns:

• project = TEAM - All work items in project
• assignee = currentUser() - Assigned to you
• status = 'In Progress' - Specific status
• created >= -7d - Created in last 7 days
• priority = High - High priority items
• labels = backend - With specific label

Edit Work Items

# Edit by key
acli jira workitem edit --key "KEY-1" --summary "Updated summary"

# Bulk edit by multiple keys
acli jira workitem edit --key "KEY-1,KEY-2,KEY-3" --assignee "[e-mail]"

# Edit via JQL query (powerful for bulk operations)
acli jira workitem edit \
  --jql "project = TEAM AND status = 'To Do'" \
  --assignee "[e-mail]"

# Edit via filter
acli jira workitem edit --filter 10001 --description "Updated description" --yes

# Update description from file
acli jira workitem edit --key "KEY-1" --description-file "new-description.txt"

# Update with ADF description (rich formatting)
acli jira workitem edit --key "KEY-1" --description '{
  "version": 1,
  "type": "doc",
  "content": [
    {
      "type": "paragraph",
      "content": [
        {"type": "text", "text": "Updated requirements:", "marks": [{"type": "strong"}]}
      ]
    },
    {
      "type": "orderedList",
      "content": [
        {
          "type": "listItem",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {"type": "text", "text": "Add error handling"}
              ]
            }
          ]
        },
        {
          "type": "listItem",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {"type": "text", "text": "Implement logging"}
              ]
            }
          ]
        }
      ]
    }
  ]
}'

# ADF description from file for bulk update
acli jira workitem edit \
  --jql "project = TEAM AND sprint = 'Sprint 10'" \
  --description-file "sprint-goals.adf.json"

# Edit labels (note: --labels plural, not --label)
acli jira workitem edit --key "KEY-1,KEY-2" --labels "frontend,backend"

# Remove specific labels
acli jira workitem edit --key "KEY-1" --remove-labels "deprecated"

# From JSON for complex updates
acli jira workitem edit --generate-json  # Generate template
acli jira workitem edit --from-json "update.json"

Key flags:

• --key: Single or comma-separated keys
• --jql: JQL query for bulk operations
• --filter: Filter ID to target work items
• --summary: Update summary
• --description: Update description (plain text or ADF)
• --description-file: Read description from file (plain text or ADF)
• --assignee: Change assignee (use '@me' for self, 'default' for project default)
• --labels / -l: Edit labels (comma-separated). Note: plural, unlike --label in create
• --remove-labels: Remove specific labels
• --yes: Skip confirmation (use with caution)

Transition Work Items

Change work item status through workflow transitions:

# Transition by key
acli jira workitem transition --key "KEY-1" --status "In Progress"

# Bulk transition by keys
acli jira workitem transition --key "KEY-1,KEY-2" --status "Done"

# Transition via JQL (very powerful)
acli jira workitem transition \
  --jql "project = TEAM AND status = 'To Do'" \
  --status "In Progress"

# Transition via filter
acli jira workitem transition --filter 10001 --status "Done" --yes

Assign Work Items

# Assign by key
acli jira workitem assign --key "KEY-1" --assignee "[e-mail]"

# Self-assign
acli jira workitem assign --key "KEY-1" --assignee "@me"

# Assign to default
acli jira workitem assign --key "KEY-1" --assignee "default"

# Unassign
acli jira workitem assign --key "KEY-1" --assignee ""

# Bulk assign via JQL
acli jira workitem assign --jql "project = TEAM" --assignee "[e-mail]"

Clone Work Items

# Clone single work item
acli jira workitem clone --key "KEY-1" --to-project "TEAM"

# Clone multiple work items
acli jira workitem clone --key "KEY-1,KEY-2" --to-project "NEWTEAM"

# Clone via JQL
acli jira workitem clone --jql "project = TEAM" --to-project "ARCHIVE"

# Clone from filter
acli jira workitem clone --filter 10001 --to-project "TEAM"

# Clone from file with work item keys
acli jira workitem clone --from-file "keys.txt" --to-project "TEAM"

Delete Work Items

# Delete single work item
acli jira workitem delete --key "KEY-1"

# Delete multiple work items
acli jira workitem delete --key "KEY-1,KEY-2,KEY-3"

# Delete via JQL
acli jira workitem delete --jql "project = OLDPROJECT"

# Delete via filter with auto-confirmation
acli jira workitem delete --filter 10001 --yes

Archive/Unarchive Work Items

# Archive work items
acli jira workitem archive --key "KEY-1,KEY-2"
acli jira workitem archive --jql "project = TEAM AND status = Done"

# Unarchive work items
acli jira workitem unarchive --key "KEY-1"
acli jira workitem unarchive --jql "project = TEAM"

Comments

Create Comments

# Create comment on single work item
acli jira workitem comment create --key "KEY-1" --body "This is a comment"

# Create comment on multiple work items
acli jira workitem comment create --key "KEY-1,KEY-2" --body "Bulk comment"

# Create comment via JQL
acli jira workitem comment create \
  --jql "project = TEAM" \
  --body "Comment on all work items"

# Create comment from file
acli jira workitem comment create --key "KEY-1" --body-file "comment.txt"

Create Comments with ADF (Rich Formatting)

ADF (Atlassian Document Format) enables rich text formatting in comments. The acli automatically detects ADF when you provide valid JSON, so no special flag is needed.

Important: Comments only support plain text or ADF. Markdown is NOT supported.

ADF Node Support: Comments vs Descriptions

Jira comments have a restricted ADF subset compared to descriptions. Using unsupported nodes will cause "Comment body is not valid!" errors.

✅ Safe for Comments:

• Block nodes: paragraph, bulletList, orderedList, codeBlock
• Inline nodes: text, hardBreak, mention
• Text marks: strong, em, code, link, strike, underline

❌ NOT Supported in Comments:

• heading (use bold paragraph instead)
• panel (use regular paragraph)
• table, tableRow, tableCell
• blockquote (may not work)
• emoji, date (may not work)
• rule (horizontal rule - may not work)

✅ Safe for Descriptions (work item create/edit):

• All comment nodes PLUS: heading, panel, table, and more

Best practice: Test ADF on a single work item before bulk operations.

Simple formatted comment (inline)

acli jira workitem comment create --key "KEY-1" --body '{
  "version": 1,
  "type": "doc",
  "content": [
    {
      "type": "paragraph",
      "content": [
        {"type": "text", "text": "Status update: "},
        {"type": "text", "text": "bug fixed", "marks": [{"type": "strong"}]},
        {"type": "text", "text": " and ready for testing."}
      ]
    }
  ]
}'

Comment with multiple paragraphs

acli jira workitem comment create --key "KEY-1" --body '{
  "version": 1,
  "type": "doc",
  "content": [
    {
      "type": "paragraph",
      "content": [
        {"type": "text", "text": "Completed the following tasks:"}
      ]
    },
    {
      "type": "bulletList",
      "content": [
        {
          "type": "listItem",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {"type": "text", "text": "Fixed authentication bug"}
              ]
            }
          ]
        },
        {
          "type": "listItem",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {"type": "text", "text": "Updated API documentation"}
              ]
            }
          ]
        }
      ]
    }
  ]
}'

Comment with code block

acli jira workitem comment create --key "KEY-1" --body '{
  "version": 1,
  "type": "doc",
  "content": [
    {
      "type": "paragraph",
      "content": [
        {"type": "text", "text": "Error found in the authentication handler:"}
      ]
    },
    {
      "type": "codeBlock",
      "attrs": {"language": "javascript"},
      "content": [
        {
          "type": "text",
          "text": "if (user.token === null) {\n  throw new Error(\"Invalid token\");\n}"
        }
      ]
    }
  ]
}'

Comment with user mention

acli jira workitem comment create --key "KEY-1" --body '{
  "version": 1,
  "type": "doc",
  "content": [
    {
      "type": "paragraph",
      "content": [
        {
          "type": "mention",
          "attrs": {"id": "557058:f58131cb-b67d-43c7-b30d-6b58d40bd077"}
        },
        {"type": "text", "text": " can you review this change?"}
      ]
    }
  ]
}'

Note: To mention a user, you need their Atlassian account ID. Get it from user profile or API.

ADF from file (recommended for complex comments)

# Create ADF file: comment.adf.json
cat > comment.adf.json << 'EOF'
{
  "version": 1,
  "type": "doc",
  "content": [
    {
      "type": "paragraph",
      "content": [
        {"type": "text", "text": "Release Notes v2.5.0", "marks": [{"type": "strong"}]}
      ]
    },
    {
      "type": "paragraph",
      "content": [
        {"type": "text", "text": "Key changes in this release:"}
      ]
    },
    {
      "type": "bulletList",
      "content": [
        {
          "type": "listItem",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {"type": "text", "text": "Performance improvements", "marks": [{"type": "strong"}]}
              ]
            }
          ]
        },
        {
          "type": "listItem",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {"type": "text", "text": "Bug fixes for edge cases"}
              ]
            }
          ]
        }
      ]
    }
  ]
}
EOF

# Use the ADF file
acli jira workitem comment create --key "KEY-1" --body-file "comment.adf.json"

# Or add to multiple work items
acli jira workitem comment create --key "KEY-1,KEY-2,KEY-3" --body-file "comment.adf.json"

Common ADF formatting patterns

Bold text:

{"type": "text", "text": "bold text", "marks": [{"type": "strong"}]}

Italic text:

{"type": "text", "text": "italic text", "marks": [{"type": "em"}]}

Inline code:

{"type": "text", "text": "code", "marks": [{"type": "code"}]}

Link:

{
  "type": "text",
  "text": "Click here",
  "marks": [{"type": "link", "attrs": {"href": "https://example.com"}}]
}

Multiple marks (bold + italic):

{
  "type": "text",
  "text": "bold and italic",
  "marks": [{"type": "strong"}, {"type": "em"}]
}

List Comments

# List all comments for a work item
acli jira workitem comment list --key "KEY-1"

# List as JSON
acli jira workitem comment list --key "KEY-1" --json

Get Comment Visibility Options

# Get available visibility options
acli jira workitem comment visibility

Attachments

List Attachments

# List attachments for a work item
acli jira workitem attachment list --key "KEY-1"

# List as JSON
acli jira workitem attachment list --key "KEY-1" --json

Download Attachments (API Workaround)

The CLI cannot download attachment content. Use the Jira REST API directly.

Requires env vars: JIRA_EMAIL, JIRA_API_TOKEN, JIRA_BASE_URL

Download single attachment:

# First list attachments to get ID and filename
acli jira workitem attachment list --key "KEY-1" --json

# Download by attachment ID
curl -L \
  -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  "$JIRA_BASE_URL/rest/api/3/attachment/content/$ATTACHMENT_ID" \
  --output "$ATTACHMENT_NAME"

Download all attachments for an issue:

# Get all attachment IDs and names, then download each
acli jira workitem attachment list --key "KEY-1" --json | \
  jq -r '.[] | "\(.id) \(.filename)"' | \
  while read -r id name; do
    curl -L -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
      "$JIRA_BASE_URL/rest/api/3/attachment/content/$id" \
      --output "$name"
  done

Project Commands

List Projects

# List default projects (30)
acli jira project list

# List recently viewed projects
acli jira project list --recent

# List all projects with pagination
acli jira project list --paginate

# List with custom limit
acli jira project list --limit 50

# Export to JSON
acli jira project list --json

View Project

# View project details
acli jira project view --project-key "TEAM"

# View as JSON
acli jira project view --project-key "TEAM" --json

Create Project

# Create from existing project
acli jira project create \
  --from-project "TEAM" \
  --key "NEWTEAM" \
  --name "New Project"

# With additional details
acli jira project create \
  --from-project "TEAM" \
  --key "NEWTEAM" \
  --name "New Project" \
  --description "Project description" \
  --url "https://example.com" \
  --lead-email "[e-mail]"

# From JSON
acli jira project create --generate-json  # Generate template
acli jira project create --from-json "project.json"

Update Project

# Update project key and name
acli jira project update \
  --project-key "TEAM1" \
  --key "TEAM" \
  --name "Updated Name"

# From JSON
acli jira project update --generate-json  # Generate template
acli jira project update --from-json "project.json"

Archive/Restore Projects

# Archive project
acli jira project archive --project-key "OLDTEAM"

# Restore archived project
acli jira project restore --project-key "OLDTEAM"

Delete Project

# Delete project
acli jira project delete --project-key "OLDPROJECT"

Dashboard Commands

# Dashboard operations (check documentation for specific commands)
acli jira dashboard --help

Filter Commands

# Filter operations (check documentation for specific commands)
acli jira filter --help

Best Practices

Bulk Operations

For bulk operations, use JQL or filters instead of comma-separated keys when possible:

# Good: Use JQL for flexible bulk operations
acli jira workitem edit --jql "project = TEAM AND status = 'To Do'" --assignee "@me"

# Good: Use filters for reusable bulk operations
acli jira workitem transition --filter 10001 --status "Done" --yes

Safety

Use --yes flag cautiously, especially with delete operations:

# Preview first by running without --yes
acli jira workitem delete --jql "project = OLDPROJECT"

# Add --yes only after verifying
acli jira workitem delete --jql "project = OLDPROJECT" --yes

JSON Templates

For complex operations, generate JSON templates first:

# Generate template
acli jira workitem create --generate-json > template.json

# Edit template.json with your data
# Then create from JSON
acli jira workitem create --from-json "template.json"

Output Formats

Use appropriate output formats for different use cases:

# Human-readable (default)
acli jira workitem view KEY-1

# JSON for scripting/parsing
acli jira workitem view KEY-1 --json

# CSV for spreadsheets
acli jira workitem search --jql "project = TEAM" --csv

Working with ADF

When working with ADF (Atlassian Document Format) for rich formatting:

When to use ADF vs Plain Text

Use ADF when you need:

• Rich text formatting (bold, italic, underline)
• Structured content (lists, headings, tables)
• Code blocks with syntax highlighting
• User mentions (@mentions)
• Links embedded in text
• Complex layouts

Use plain text when:

• Simple status updates or short notes
• Automation scripts where formatting isn't needed
• Quick comments without special formatting
• Performance is critical (ADF is more verbose)

Auto-detection

The acli automatically detects whether input is plain text or ADF JSON. No special flag is required:

# Plain text - automatically detected
acli jira workitem comment create --key "KEY-1" --body "Simple comment"

# ADF - automatically detected by JSON structure
acli jira workitem comment create --key "KEY-1" --body '{"version": 1, "type": "doc", "content": [...]}'

Best practices for ADF

1. Use files for reusability:

# Create reusable ADF templates
cat > templates/status-update.adf.json << 'EOF'
{
  "version": 1,
  "type": "doc",
  "content": [...]
}
EOF

# Reuse across multiple work items
acli jira workitem comment create --key "KEY-1,KEY-2" --body-file "templates/status-update.adf.json"

2. Test ADF before bulk operations:

# Test on single work item first
acli jira workitem comment create --key "KEY-TEST" --body-file "comment.adf.json"

# Verify it looks correct in Jira UI
acli jira workitem view KEY-TEST --web

# Then apply to multiple items
acli jira workitem comment create --jql "project = TEAM" --body-file "comment.adf.json"

3. Keep ADF simple and maintainable:

# Good: Simple, readable structure
{
  "version": 1,
  "type": "doc",
  "content": [
    {
      "type": "paragraph",
      "content": [
        {"type": "text", "text": "Status: "},
        {"type": "text", "text": "Complete", "marks": [{"type": "strong"}]}
      ]
    }
  ]
}

# Avoid: Overly complex nested structures that are hard to maintain

4. Validate ADF structure:

Ensure your ADF always includes:

• "version": 1 - Required ADF version
• "type": "doc" - Required root node type
• "content": [...] - Array of block nodes (can be empty)

5. Common patterns for building ADF programmatically:

# Using jq to build ADF dynamically
ISSUE_KEY="KEY-1"
STATUS="Complete"

jq -n --arg status "$STATUS" '{
  "version": 1,
  "type": "doc",
  "content": [
    {
      "type": "paragraph",
      "content": [
        {"type": "text", "text": "Status: "},
        {"type": "text", "text": $status, "marks": [{"type": "strong"}]}
      ]
    }
  ]
}' | acli jira workitem comment create --key "$ISSUE_KEY" --body "$(cat)"

Common ADF issues and solutions

Issue: "Comment body is not valid!" error

• Cause: Using ADF nodes that aren't supported in comments (heading, panel, table, etc.)
• Solution: Stick to safe comment nodes: paragraph, bulletList, orderedList, codeBlock, text, and basic marks
• Example fix: Replace {"type": "heading"} with {"type": "paragraph", "content": [{"type": "text", "text": "...", "marks": [{"type": "strong"}]}]}

Issue: Comment appears as raw JSON text

• Cause: Invalid ADF structure or missing required fields
• Solution: Validate that version, type, and content are present

Issue: Special characters break the ADF

• Cause: Unescaped quotes or special characters in bash
• Solution: Use files (--body-file) instead of inline JSON for complex content

Issue: User mention doesn't work

• Cause: Incorrect account ID format
• Solution: Get exact account ID from user profile or API, format: 557058:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Issue: ADF works in descriptions but fails in comments

• Cause: Comments have a more restricted ADF subset than descriptions
• Solution: See "ADF Node Support: Comments vs Descriptions" section above for safe nodes

ADF Quick Reference

Complete reference for ADF (Atlassian Document Format) node types and formatting options.

Basic Structure

Minimum valid ADF document:

{
  "version": 1,
  "type": "doc",
  "content": []
}

Simple paragraph:

{
  "version": 1,
  "type": "doc",
  "content": [
    {
      "type": "paragraph",
      "content": [
        {"type": "text", "text": "Hello world"}
      ]
    }
  ]
}

Text Formatting (Marks)

Bold (strong):

{"type": "text", "text": "bold text", "marks": [{"type": "strong"}]}

Italic (emphasis):

{"type": "text", "text": "italic text", "marks": [{"type": "em"}]}

Underline:

{"type": "text", "text": "underlined", "marks": [{"type": "underline"}]}

Strikethrough:

{"type": "text", "text": "deleted", "marks": [{"type": "strike"}]}

Inline code:

{"type": "text", "text": "code", "marks": [{"type": "code"}]}

Link:

{
  "type": "text",
  "text": "Click here",
  "marks": [
    {
      "type": "link",
      "attrs": {"href": "https://example.com"}
    }
  ]
}

Combined formatting (bold + italic):

{
  "type": "text",
  "text": "bold and italic",
  "marks": [
    {"type": "strong"},
    {"type": "em"}
  ]
}

Headings

⚠️ NOT supported in comments - Use bold paragraphs instead. Works in descriptions only.

Heading levels 1-6:

{
  "type": "heading",
  "attrs": {"level": 1},
  "content": [
    {"type": "text", "text": "Heading 1"}
  ]
}

Available levels: 1, 2, 3, 4, 5, 6

Comment-safe alternative:

{
  "type": "paragraph",
  "content": [
    {"type": "text", "text": "Heading Text", "marks": [{"type": "strong"}]}
  ]
}

Lists

Bullet list:

{
  "type": "bulletList",
  "content": [
    {
      "type": "listItem",
      "content": [
        {
          "type": "paragraph",
          "content": [
            {"type": "text", "text": "First item"}
          ]
        }
      ]
    },
    {
      "type": "listItem",
      "content": [
        {
          "type": "paragraph",
          "content": [
            {"type": "text", "text": "Second item"}
          ]
        }
      ]
    }
  ]
}

Ordered list:

{
  "type": "orderedList",
  "content": [
    {
      "type": "listItem",
      "content": [
        {
          "type": "paragraph",
          "content": [
            {"type": "text", "text": "First item"}
          ]
        }
      ]
    }
  ]
}

Nested lists:

{
  "type": "bulletList",
  "content": [
    {
      "type": "listItem",
      "content": [
        {
          "type": "paragraph",
          "content": [
            {"type": "text", "text": "Parent item"}
          ]
        },
        {
          "type": "bulletList",
          "content": [
            {
              "type": "listItem",
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {"type": "text", "text": "Nested item"}
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Code Blocks

Code block with language:

{
  "type": "codeBlock",
  "attrs": {"language": "javascript"},
  "content": [
    {
      "type": "text",
      "text": "function hello() {\n  console.log('Hello');\n}"
    }
  ]
}

Supported languages: javascript, python, java, typescript, bash, sql, json, xml, html, css, etc.

Code block without language:

{
  "type": "codeBlock",
  "content": [
    {"type": "text", "text": "Plain code block"}
  ]
}

Mentions

User mention:

{
  "type": "mention",
  "attrs": {
    "id": "557058:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

Note: Get user account ID from Jira user profile or API.

Panels (Colored Blocks)

⚠️ NOT supported in comments - Use regular paragraphs instead. Works in descriptions only.

Info panel:

{
  "type": "panel",
  "attrs": {"panelType": "info"},
  "content": [
    {
      "type": "paragraph",
      "content": [
        {"type": "text", "text": "This is an info panel"}
      ]
    }
  ]
}

Panel types: info, note, warning, error, success

Block Quote

{
  "type": "blockquote",
  "content": [
    {
      "type": "paragraph",
      "content": [
        {"type": "text", "text": "This is a quote"}
      ]
    }
  ]
}

Horizontal Rule

{
  "type": "rule"
}

Hard Break

Line break within paragraph:

{
  "type": "paragraph",
  "content": [
    {"type": "text", "text": "First line"},
    {"type": "hardBreak"},
    {"type": "text", "text": "Second line"}
  ]
}

Emoji

{
  "type": "emoji",
  "attrs": {
    "shortName": ":smile:",
    "id": "1f604",
    "text": "😄"
  }
}

Date

{
  "type": "date",
  "attrs": {
    "timestamp": "1672531200000"
  }
}

Ready-to-Use Templates

Status update with formatting:

{
  "version": 1,
  "type": "doc",
  "content": [
    {
      "type": "paragraph",
      "content": [
        {"type": "text", "text": "Status: ", "marks": [{"type": "strong"}]},
        {"type": "text", "text": "Completed ✓", "marks": [{"type": "strong"}, {"type": "em"}]}
      ]
    },
    {
      "type": "paragraph",
      "content": [
        {"type": "text", "text": "Next steps: Review and merge PR"}
      ]
    }
  ]
}

Bug report with code:

{
  "version": 1,
  "type": "doc",
  "content": [
    {
      "type": "paragraph",
      "content": [
        {"type": "text", "text": "Found a bug in the authentication handler:", "marks": [{"type": "strong"}]}
      ]
    },
    {
      "type": "codeBlock",
      "attrs": {"language": "javascript"},
      "content": [
        {"type": "text", "text": "if (token === undefined) {\n  // Missing validation\n}"}
      ]
    },
    {
      "type": "paragraph",
      "content": [
        {"type": "text", "text": "Expected behavior: Should throw an error when token is undefined"}
      ]
    }
  ]
}

Release notes (for descriptions only - uses heading and panel):

{
  "version": 1,
  "type": "doc",
  "content": [
    {
      "type": "heading",
      "attrs": {"level": 3},
      "content": [
        {"type": "text", "text": "Release v2.5.0"}
      ]
    },
    {
      "type": "panel",
      "attrs": {"panelType": "success"},
      "content": [
        {
          "type": "paragraph",
          "content": [
            {"type": "text", "text": "Ready for production deployment"}
          ]
        }
      ]
    },
    {
      "type": "paragraph",
      "content": [
        {"type": "text", "text": "New features:", "marks": [{"type": "strong"}]}
      ]
    },
    {
      "type": "bulletList",
      "content": [
        {
          "type": "listItem",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {"type": "text", "text": "Enhanced authentication"}
              ]
            }
          ]
        },
        {
          "type": "listItem",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {"type": "text", "text": "Performance improvements"}
              ]
            }
          ]
        }
      ]
    }
  ]
}

Release notes (comment-safe version):

{
  "version": 1,
  "type": "doc",
  "content": [
    {
      "type": "paragraph",
      "content": [
        {"type": "text", "text": "Release v2.5.0", "marks": [{"type": "strong"}]}
      ]
    },
    {
      "type": "paragraph",
      "content": [
        {"type": "text", "text": "✅ Ready for production deployment", "marks": [{"type": "em"}]}
      ]
    },
    {
      "type": "paragraph",
      "content": [
        {"type": "text", "text": "New features:", "marks": [{"type": "strong"}]}
      ]
    },
    {
      "type": "bulletList",
      "content": [
        {
          "type": "listItem",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {"type": "text", "text": "Enhanced authentication"}
              ]
            }
          ]
        },
        {
          "type": "listItem",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {"type": "text", "text": "Performance improvements"}
              ]
            }
          ]
        }
      ]
    }
  ]
}

Integration with Claude Code

When using this skill in Claude Code:

1. Always check authentication first: Run acli jira auth login --web if needed
2. Use bash_tool: Execute acli commands using bash_tool
3. Parse output: Use --json flag for programmatic parsing
4. Handle errors: Check return codes and provide helpful error messages
5. Confirm destructive operations: Always warn before delete/bulk operations
6. Use JQL for filtering: Prefer JQL over manual key lists for bulk operations

Common Use Cases

Daily Workflow

# View your assigned work items
acli jira workitem search --jql "assignee = currentUser() AND status != Done"

# Transition work to in progress
acli jira workitem transition --key "KEY-1" --status "In Progress"

# Add comment
acli jira workitem comment create --key "KEY-1" --body "Started working on this"

Bulk Updates

# Reassign all open items in a sprint
acli jira workitem edit \
  --jql "sprint = 'Sprint 10' AND status != Done" \
  --assignee "[e-mail]"

# Close all resolved items
acli jira workitem transition \
  --jql "project = TEAM AND resolution is not EMPTY" \
  --status "Done"

Project Migration

# Clone all items from one project to another
acli jira workitem clone \
  --jql "project = OLDTEAM" \
  --to-project "NEWTEAM"

# Archive old project
acli jira project archive --project-key "OLDTEAM"

Reporting

# Export all items to CSV
acli jira workitem search \
  --jql "project = TEAM AND created >= -30d" \
  --fields "key,summary,status,assignee,created" \
  --csv > report.csv

# Count items by status
acli jira workitem search --jql "project = TEAM AND status = 'To Do'" --count
acli jira workitem search --jql "project = TEAM AND status = 'In Progress'" --count
acli jira workitem search --jql "project = TEAM AND status = 'Done'" --count

Help and Documentation

Get help for any command:

# Main help
acli --help

# Jira commands help
acli jira --help

# Work item commands help
acli jira workitem --help

# Specific command help
acli jira workitem create --help

Gotchas

--label vs --labels (edit ≠ create)

create and edit use different flag names for labels:

Command	Flag	Type
workitem create	--label (singular)	strings
workitem edit	--labels (plural)	string
workitem edit	--remove-labels	string

Using --label with edit produces unknown flag: --label.

# ✗ WRONG — --label is not a flag on edit
acli jira workitem edit --key "KEY-1" --label "my-label" --yes

# ✓ CORRECT — use --labels (plural)
acli jira workitem edit --key "KEY-1" --labels "my-label" --yes

Prefer comma-separated --key over shell loops

--key accepts comma-separated values. Use that instead of looping:

# ✗ Slower, noisier
for key in KEY-1 KEY-2 KEY-3; do acli jira workitem edit --key "$key" --labels "foo" --yes; done

# ✓ Single API-efficient call
acli jira workitem edit --key "KEY-1,KEY-2,KEY-3" --labels "foo" --yes

Important Notes

• Work items vs Issues: ACLI uses "workitem" terminology instead of "issue"
• Authentication required: Must authenticate before using any commands
• Cloud only: ACLI is for Jira Cloud, not Data Center or Server
• Atlassian Government Cloud: Not supported
• Pagination: Use --paginate for large result sets
• Rate limits: Be mindful of API rate limits for bulk operations