atlassian-cli-jira

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

Before using any Jira commands, authenticate using OAuth:

```bash

# Interactive OAuth login (recommended)

acli jira auth login --web

# Login with API token (for automation)

echo | acli jira auth login --site "mysite.atlassian.net" --email "user@atlassian.com" --token

```

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

Create Work Items

```bash

# 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 "user@example.com" \

--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

```bash

# 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:

```bash

# 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

```bash

# 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 "user@example.com"

# Edit via JQL query (powerful for bulk operations)

acli jira workitem edit \

--jql "project = TEAM AND status = 'To Do'" \

--assignee "user@example.com"

# 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"

# 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)
• --yes: Skip confirmation (use with caution)

Transition Work Items

Change work item status through workflow transitions:

```bash

# 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

```bash

# Assign by key

acli jira workitem assign --key "KEY-1" --assignee "user@example.com"

# 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 "user@example.com"

```

Clone Work Items

```bash

# 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

```bash

# 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

```bash

# 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"

```

Create Comments

```bash

# 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)

```bash

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

```bash

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

```bash

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

```bash

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)

```bash

# 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:

```json

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

```

Italic text:

```json

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

```

Inline code:

```json

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

```

Link:

```json

{

"type": "text",

"text": "Click here",

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

}

```

Multiple marks (bold + italic):

```json

{

"type": "text",

"text": "bold and italic",

"marks": [{"type": "strong"}, {"type": "em"}]

}

```

List Comments

```bash

# 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

```bash

# Get available visibility options

acli jira workitem comment visibility

```

List Attachments

```bash

# 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:

```bash

# 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:

```bash

# 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

```

List Projects

```bash

# 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

```bash

# View project details

acli jira project view --project-key "TEAM"

# View as JSON

acli jira project view --project-key "TEAM" --json

```

Create Project

```bash

# 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 "user@example.com"

# From JSON

acli jira project create --generate-json # Generate template

acli jira project create --from-json "project.json"

```

Update Project

```bash

# 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

```bash

# Archive project

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

# Restore archived project

acli jira project restore --project-key "OLDTEAM"

```

Delete Project

```bash

# Delete project

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

```

```bash

# Dashboard operations (check documentation for specific commands)

acli jira dashboard --help

```

```bash

# Filter operations (check documentation for specific commands)

acli jira filter --help

```

Bulk Operations

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

```bash

# 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:

```bash

# 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:

```bash

# 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:

```bash

# 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:

```bash

# 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:

```bash

# 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:

```bash

# 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:

```bash

# 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:

```bash

# 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

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

Basic Structure

Minimum valid ADF document:

```json

{

"version": 1,

"type": "doc",

"content": []

}

```

Simple paragraph:

```json

{

"version": 1,

"type": "doc",

"content": [

{

"type": "paragraph",

"content": [

{"type": "text", "text": "Hello world"}

]

}

]

}

```

Text Formatting (Marks)

Bold (strong):

```json

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

```

Italic (emphasis):

```json

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

```

Underline:

```json

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

```

Strikethrough:

```json

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

```

Inline code:

```json

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

```

Link:

```json

{

"type": "text",

"text": "Click here",

"marks": [

{

"type": "link",

"attrs": {"href": "https://example.com"}

}

]

}

```

Combined formatting (bold + italic):

```json

{

"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:

```json

{

"type": "heading",

"attrs": {"level": 1},

"content": [

{"type": "text", "text": "Heading 1"}

]

}

```

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

Comment-safe alternative:

```json

{

"type": "paragraph",

"content": [

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

]

}

```

Lists

Bullet list:

```json

{

"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:

```json

{

"type": "orderedList",

"content": [

{

"type": "listItem",

"content": [

{

"type": "paragraph",

"content": [

{"type": "text", "text": "First item"}

]

}

]

}

]

}

```

Nested lists:

```json

{

"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:

```json

{

"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:

```json

{

"type": "codeBlock",

"content": [

{"type": "text", "text": "Plain code block"}

]

}

```

Mentions

User mention:

```json

{

"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:

```json

{

"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

```json

{

"type": "blockquote",

"content": [

{

"type": "paragraph",

"content": [

{"type": "text", "text": "This is a quote"}

]

}

]

}

```

Horizontal Rule

```json

{

"type": "rule"

}

```

Hard Break

Line break within paragraph:

```json

{

"type": "paragraph",

"content": [

{"type": "text", "text": "First line"},

{"type": "hardBreak"},

{"type": "text", "text": "Second line"}

]

}

```

Emoji

```json

{

"type": "emoji",

"attrs": {

"shortName": ":smile:",

"id": "1f604",

"text": "😄"

}

}

```

Date

```json

{

"type": "date",

"attrs": {

"timestamp": "1672531200000"

}

}

```

Ready-to-Use Templates

Status update with formatting:

```json

{

"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:

```json

{

"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):

```json

{

"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):

```json

{

"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"}

]

}

]

}

]

}

]

}

```

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

Daily Workflow

```bash

# 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

```bash

# Reassign all open items in a sprint

acli jira workitem edit \

--jql "sprint = 'Sprint 10' AND status != Done" \

--assignee "new-owner@example.com"

# Close all resolved items

acli jira workitem transition \

--jql "project = TEAM AND resolution is not EMPTY" \

--status "Done"

```

Project Migration

```bash

# 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

```bash

# 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

```

Get help for any command:

```bash

# 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

```

• 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