Atlassian CLI (acli)

Overview

The Atlassian CLI (acli) provides command-line access to Jira, Confluence, and other Atlassian products. Core principle: Always check authentication first, use correct command structure, and leverage batch operations.

When to Use

• Creating, searching, or updating Jira issues
• Managing sprints, boards, or projects
• Working with Confluence spaces
• Bulk operations on multiple items
• Generating reports in CSV/JSON format
• Automating Atlassian workflows

When NOT to use:

• When web UI is more appropriate (one-off visual tasks)
• When API tokens/integrations are already available

Authentication - FIRST STEP ALWAYS

digraph auth_check {
    "User requests acli command" [shape=doublecircle];
    "Check auth status" [shape=box];
    "Authenticated?" [shape=diamond];
    "Run acli command" [shape=box];
    "Explain: acli auth login" [shape=box];

    "User requests acli command" -> "Check auth status";
    "Check auth status" -> "Authenticated?";
    "Authenticated?" -> "Run acli command" [label="yes"];
    "Authenticated?" -> "Explain: acli auth login" [label="no"];
}

Before ANY acli operation:

# Check if authenticated
acli auth status

# If not authenticated, login first
acli auth login

Command Structure

Format: acli <product> <entity> <action> [flags]

DO NOT use old-style syntax with --action flag.

# ❌ WRONG - old syntax that doesn't work
acli jira --action getIssueList --jql "..."

# ✅ CORRECT - modern syntax
acli jira workitem search --jql "..."

Quick Reference

Common Products

• auth - Authentication management
• jira - Jira Cloud commands
• confluence - Confluence Cloud commands
• admin - Admin operations

Jira Entities & Actions

Confluence Entities

Batch Operations

Use JQL, filters, or key lists to operate on multiple items:

# Edit multiple issues with JQL
acli jira workitem edit --jql "project = MOBILE AND status = 'In Review'" --assignee "user@example.com" --yes

# Transition multiple issues
acli jira workitem transition --jql "assignee = currentUser() AND status = 'To Do'" --status "In Progress" --yes

# Search with filter
acli jira workitem search --filter 10001 --csv

# Multiple keys
acli jira workitem assign --key "KEY-1,KEY-2,KEY-3" --assignee "@me"

Batch flags:

• --jql - JQL query for multiple items
• --filter - Filter ID for saved searches
• --key - Comma-separated issue keys
• --yes / -y - Skip confirmation prompts
• --ignore-errors - Continue on errors (useful for bulk ops)

Output Formats

Choose the right output format for your use case:

# CSV for spreadsheets
acli jira workitem search --jql "sprint = 42" --csv

# JSON for scripts/automation
acli jira workitem search --jql "project = API" --json

# Web browser for viewing
acli jira workitem view KEY-123 --web

# Custom fields (default includes key, summary, status, etc.)
acli jira workitem search --jql "..." --fields "key,summary,assignee,priority"

Common flags:

• --csv - CSV output (NOT --outputFormat 999)
• --json - JSON output
• --web - Open in web browser
• --fields - Specify which fields to display (NOT --columns)
• --count - Show count only
• --paginate - Fetch all results

Bulk Creation

For creating multiple similar issues:

# Generate JSON template
acli jira workitem create --generate-json

# Create from JSON file
acli jira workitem create --from-json workitem.json

# Bulk create multiple issues
acli jira workitem create-bulk

# Use file for description
acli jira workitem create --summary "Bug title" --project API --type Bug --from-file description.txt

# Use editor for interactive creation
acli jira workitem create --editor

Don't create bash loops with 10 individual create commands when create-bulk or --from-json exists.

Common JQL Patterns

# Current user's issues
--jql "assignee = currentUser()"

# Specific project and status
--jql "project = TEAM AND status = 'In Progress'"

# Multiple criteria
--jql "project = API AND type = Bug AND status != Done"

# Sprint issues
--jql "project = TEAM AND sprint = 42"

# Recent updates
--jql "project = WEBAPP AND updated >= -7d"

Common Mistakes

Red Flags - STOP and Check Skill

These indicate you're about to make a mistake:

• Skipping authentication check
• Using --action in your command
• Writing bash loops for bulk operations
• Suggesting --outputFormat instead of --csv
• Using --columns instead of --fields
• Making up command names without checking --help
• "The old syntax probably still works"
• "They're probably already authenticated"
• "A bash loop is more flexible than built-in commands"

All of these mean: Stop, re-read this skill, use correct syntax.

Workflow Pattern

digraph workflow {
    "acli request" [shape=doublecircle];
    "Check auth status" [shape=box];
    "Authenticated?" [shape=diamond];
    "Run acli auth login" [shape=box];
    "Verify command with --help" [shape=box];
    "Check for batch operation?" [shape=diamond];
    "Use --jql/--filter/--key" [shape=box];
    "Single operation" [shape=box];
    "Choose output format" [shape=box];
    "Execute command" [shape=box];

    "acli request" -> "Check auth status";
    "Check auth status" -> "Authenticated?";
    "Authenticated?" -> "Run acli auth login" [label="no"];
    "Run acli auth login" -> "Verify command with --help";
    "Authenticated?" -> "Verify command with --help" [label="yes"];
    "Verify command with --help" -> "Check for batch operation?";
    "Check for batch operation?" -> "Use --jql/--filter/--key" [label="multiple items"];
    "Check for batch operation?" -> "Single operation" [label="single item"];
    "Use --jql/--filter/--key" -> "Choose output format";
    "Single operation" -> "Choose output format";
    "Choose output format" -> "Execute command";
}

Example Workflows

Sprint Report

# 1. Check auth
acli auth status

# 2. Search sprint issues with CSV output
acli jira workitem search --jql "project = TEAM AND sprint = 42" --fields "key,summary,status,assignee" --csv > sprint-report.csv

Bulk Status Update

# 1. Check auth
acli auth status

# 2. Verify issues first
acli jira workitem search --jql "project = MOBILE AND status = 'In Review'" --count

# 3. Transition all
acli jira workitem transition --jql "project = MOBILE AND status = 'In Review'" --status "Done" --yes

# 4. Assign all
acli jira workitem assign --jql "project = MOBILE AND status = Done" --assignee "user@example.com" --yes

Create Multiple Issues

# 1. Check auth
acli auth status

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

# 3. Edit template.json with your data

# 4. Create from template (repeat for each)
acli jira workitem create --from-json issue1.json
acli jira workitem create --from-json issue2.json

# OR use create-bulk
acli jira workitem create-bulk

Getting Help

# Top-level help
acli --help

# Product help
acli jira --help

# Entity help
acli jira workitem --help

# Action help
acli jira workitem search --help

When in doubt, check --help for exact flags and syntax.