acli

name	acli
description	Work with Atlassian products (Jira and Confluence) using the Atlassian CLI. Use when the user needs to create, view, edit, search, or manage Jira work items, projects, boards, sprints, filters, or Confluence spaces. Also use for authentication, user management, or automation of Atlassian workflows.
license	MIT
compatibility	opencode
metadata	{"category":"atlassian","tools":"acli"}

Atlassian CLI (acli)

Use the Atlassian CLI to interact with Jira and Confluence from the command line.

Project-Specific Configuration

InfraGraph Project (IG)

Project Information:

• Project Key: IG
• Team Field: customfield_10001
• Default Team Value: InfraGraph-Graph Engine

Creating Issues:

When creating Jira issues for the InfraGraph project, always include the team field:

# Create a task with team field
acli jira workitem create \
  --project IG \
  --type Task \
  --summary "Task summary" \
  --description "Task description" \
  --custom "customfield_10001=InfraGraph-Graph Engine"

Linking to Epics:

When creating issues under an epic, use the --parent flag. This automatically inherits the team field from the parent epic:

# Create a subtask under an epic (team field inherited)
acli jira workitem create \
  --project IG \
  --type Task \
  --summary "Subtask summary" \
  --description "Task description" \
  --parent IG-1234

Note: When linking to an epic via --parent, you don't need to explicitly set customfield_10001 as it will be inherited from the parent.

Authentication

Authentication Methods

There are two ways to authenticate with acli:

1. OAuth (Web Browser) - Global Authentication:

# Authenticate globally via OAuth (opens browser)
acli auth login

# OR for Jira-specific OAuth
acli jira auth login --web

2. API Token - Product-Specific Authentication:

For organizations where OAuth is not enabled, use an API token:

# Authenticate with API token (Linux/Mac)
echo "your-api-token" | acli jira auth login --site "mysite.atlassian.net" --email "[e-mail]" --token

# OR read token from file
acli jira auth login --site "mysite.atlassian.net" --email "[e-mail]" --token < token.txt

# Windows users
Get-Content token.txt | .\acli.exe jira auth login --site "mysite.atlassian.net" --email "[e-mail]" --token

To create an API token:

1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
2. Click "Create API token"
3. Give it a name and copy the token
4. Use it with the --token flag as shown above

Note: API token authentication is product-specific (e.g., acli jira auth login), while OAuth can be global (acli auth login).

Check Authentication Status

acli auth status
# OR for product-specific status
acli jira auth status

Switch Between Accounts

acli auth switch
# OR for product-specific
acli jira auth switch

Common Workflows

Working with Jira Work Items

Search for work items:

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

# Find work items by project
acli jira workitem search --jql "project = PROJ AND status = 'In Progress'"

# Search with specific fields and output formats
acli jira workitem search --jql "project = PROJ AND created >= -7d" --fields "key,summary,assignee" --csv

# Limit results or paginate through all
acli jira workitem search --jql "project = PROJ" --limit 50 --json
acli jira workitem search --jql "project = PROJ" --paginate

# Get count of matching work items
acli jira workitem search --jql "project = PROJ" --count

# Search using a saved filter
acli jira workitem search --filter 10001

View work item details:

acli jira workitem view KEY-123

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

# View in JSON format
acli jira workitem view KEY-123 --json

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

Create a work item:

# Create a task
acli jira workitem create --project PROJ --type Task --summary "Fix login bug"

# Create with description and assignee
acli jira workitem create --project PROJ --type Task --summary "Implement feature" --description "Detailed description here" --assignee "[e-mail]"

# Self-assign with @me
acli jira workitem create --project PROJ --type Bug --summary "Fix crash" --assignee "@me" --label "bug,critical"

# Create with a parent (subtask)
acli jira workitem create --project PROJ --type Task --summary "Subtask" --parent KEY-100

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

Edit a work item:

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

# Edit multiple work items
acli jira workitem edit --key "KEY-1,KEY-2" --assignee "[e-mail]"

# Edit work items matching a JQL query
acli jira workitem edit --jql "project = PROJ" --assignee "[e-mail]" --yes

Transition work item status:

# Move to a different status
acli jira workitem transition --key "KEY-123" --status "In Progress"

# Transition multiple work items
acli jira workitem transition --key "KEY-1,KEY-2" --status "Done"

# Transition by JQL query
acli jira workitem transition --jql "project = PROJ" --status "In Progress" --yes

Assign work item:

# Assign to a user
acli jira workitem assign --key "KEY-123" --assignee "[e-mail]"

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

# Remove assignee
acli jira workitem assign --key "KEY-123" --remove-assignee

Link work items:

# Create a link between work items
acli jira workitem link create --out KEY-123 --in KEY-456 --type Blocks

# List links on a work item
acli jira workitem link list --key KEY-123

# View available link types
acli jira workitem link type

Clone work item:

# Clone a work item
acli jira workitem clone --key "KEY-123"

# Clone to a different project
acli jira workitem clone --key "KEY-123" --to-project "OTHER"

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

Delete work item:

# Delete a work item
acli jira workitem delete --key "KEY-123"

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

# Delete by JQL query
acli jira workitem delete --jql "project = PROJ AND status = Done" --yes

Comments:

# List comments
acli jira workitem comment list --key KEY-123

# Create a comment
acli jira workitem comment create --key KEY-123 --body "This is a comment"

# Update a comment
acli jira workitem comment update --key KEY-123 --comment-id 12345 --body "Updated comment"

# Delete a comment
acli jira workitem comment delete --key KEY-123 --comment-id 12345

Attachments and watchers:

# List attachments
acli jira workitem attachment list --key KEY-123

# List watchers
acli jira workitem watcher list --key KEY-123

# Remove a watcher
acli jira workitem watcher remove --key KEY-123 --account-id "user-account-id"

Archive/unarchive:

acli jira workitem archive --key "KEY-123"
acli jira workitem unarchive --key "KEY-123"

Managing Jira Projects

List projects:

# List projects (default limit 30)
acli jira project list

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

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

# Output as JSON
acli jira project list --limit 50 --json

View project details:

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

Create project:

# Create a project cloned from an existing project
acli jira project create --from-project "EXISTING" --key "NEWPROJ" --name "New Project"

# With optional fields
acli jira project create --from-project "EXISTING" --key "NEWPROJ" --name "New Project" --description "Project description" --lead-email "[e-mail]"

# Create from a JSON file
acli jira project create --from-json "project.json"

# Generate a JSON template for project creation
acli jira project create --generate-json

Update project:

# Update project description
acli jira project update --project-key "PROJ" --description "Updated description"

# Update project name and key
acli jira project update --project-key "PROJ" --name "New Name" --key "NEWKEY"

Archive/restore projects:

acli jira project archive --key "PROJ"
acli jira project restore --key "PROJ"

Delete project:

acli jira project delete --key "PROJ"

Boards and Sprints

Search boards:

# Search by project
acli jira board search --project PROJ

# Search by name
acli jira board search --name "My Board"

# Filter by type
acli jira board search --type scrum

List sprints for a board:

# List all sprints for a board
acli jira board list-sprints --id 123

# Filter by sprint state
acli jira board list-sprints --id 123 --state active,closed

Sprint management:

# View sprint details
acli jira sprint view --id 456

# List work items in a sprint (both --sprint and --board are required)
acli jira sprint list-workitems --sprint 456 --board 123

# Create/update/delete sprints
acli jira sprint create -h
acli jira sprint update -h
acli jira sprint delete -h

Filters

List filters:

# List my filters
acli jira filter list --my

# List my favourite filters
acli jira filter list --favourite

Search filters:

acli jira filter search --name "My Filter"
acli jira filter search --owner "[e-mail]"

Add filter to favourites:

acli jira filter add-favourite --filter-id 10001

Other filter commands:

acli jira filter get --id 10001
acli jira filter update -h
acli jira filter change-owner -h

Confluence

Space management:

# List spaces
acli confluence space list

# View space details
acli confluence space view --key "SPACE"

# Create a space
acli confluence space create -h

# Update a space
acli confluence space update -h

# Archive/restore a space
acli confluence space archive --key "SPACE"
acli confluence space restore --key "SPACE"

Authentication (same patterns as Jira):

acli confluence auth login --web
# OR with API token
echo "token" | acli confluence auth login --site "mysite.atlassian.net" --email "[e-mail]" --token

Administrative Tasks

User management:

# Admin auth (separate from product auth)
acli admin auth login

# User commands
acli admin user activate -h
acli admin user deactivate -h
acli admin user delete -h
acli admin user cancel-delete -h

Dashboards and Fields

# Search dashboards
acli jira dashboard search -h

# Custom field management
acli jira field create -h
acli jira field delete -h
acli jira field cancel-delete -h

Discovery Pattern

For any command, use the -h or --help flag to discover available options:

# Top-level help
acli -h

# Command-specific help
acli jira -h
acli jira workitem -h
acli jira workitem create -h

Minimizing Output Size (Token Conservation)

acli returns raw Jira REST API v3 responses - it does not strip or transform the payload. This means descriptions come back as Atlassian Document Format (ADF), a deeply nested JSON structure that can be hundreds of lines for a single field. Always filter output aggressively to avoid wasting tokens.

Use --fields to request only what you need

Both workitem view and workitem search support --fields to limit returned fields:

# View: only get summary and status (skips the massive ADF description, comments, etc.)
acli jira workitem view KEY-123 --fields "summary,status"

# View: get everything except description
acli jira workitem view KEY-123 --fields "-description"

# Search: only key, summary, and assignee
acli jira workitem search --jql "project = PROJ" --fields "key,summary,assignee"

Default fields for view: key,issuetype,summary,status,assignee,description Default fields for search: issuetype,key,assignee,priority,status,summary

If you don't need the description, explicitly exclude it - it's the single biggest source of bloat due to ADF encoding.

Use --json with jq for surgical extraction

When you need structured data from verbose responses, pipe through jq:

# Get just the summary and status as plain text
acli jira workitem view KEY-123 --json | jq '{key: .key, summary: .fields.summary, status: .fields.status.name}'

# Extract comment bodies from a work item
acli jira workitem view KEY-123 --fields "comment" --json | jq '[.fields.comment.comments[] | {author: .author.displayName, body: .body}]'

# Get a compact list from search results
acli jira workitem search --jql "assignee = currentUser()" --json | jq '[.[] | {key: .key, summary: .fields.summary, status: .fields.status.name}]'

Use --csv for tabular summaries

For search results you just need to scan, --csv is far more compact than JSON or default output:

acli jira workitem search --jql "project = PROJ AND status != Done" --fields "key,summary,status,assignee" --csv

Use --count when you only need a number

acli jira workitem search --jql "project = PROJ AND sprint in openSprints()" --count

Prefer search over view for bulk lookups

Rather than calling workitem view in a loop (each returning the full payload), use a single workitem search with a JQL key in (KEY-1, KEY-2, KEY-3) query and --fields to get exactly what you need in one call.

ADF description handling

Jira descriptions are stored in Atlassian Document Format - a deeply nested JSON tree, not plain text or markdown. When the user asks about a work item's description, either:

1. Exclude it with --fields "-description" and tell the user to check the web UI, or
2. Fetch it and extract the text content nodes from the ADF with jq, e.g.:

acli jira workitem view KEY-123 --fields "description" --json | jq '[recurse(.content[]?) | select(.type == "text") | .text] | join("")'

Status categories

Jira statuses (e.g. "In Review", "Code Review") map to three built-in status categories: To Do, In Progress, and Done. When filtering by status in JQL, use the exact status name (e.g. status = "In Review"), or use statusCategory for broader matching (e.g. statusCategory = "In Progress" catches all active statuses).

Best Practices

1. Filter output aggressively - Always use --fields, --json | jq, or --csv to minimize token usage
2. Use JQL for searches - JQL (Jira Query Language) provides powerful search capabilities
3. Discover options with --help - Commands have many flags and options; always check help when unsure
4. Use output format flags - Most commands support --json and --csv for structured output
5. Use --paginate for large result sets - Avoids missing results due to default limits
6. Present clean output - Parse command output to present relevant information to the user
7. Verify permissions - Some operations require specific Jira/Confluence permissions

Error Handling

If commands fail with authentication errors:

• Check authentication status with acli auth status or acli jira auth status
• Authenticate using the appropriate method:
  • For OAuth: acli auth login or acli jira auth login --web
  • For API token: acli jira auth login --site "site" --email "email" --token
• If OAuth is not available in the organization, use API token authentication

For other errors:

• Permission errors: Explain that the user may not have necessary permissions
• Not found errors: Verify work item keys, project keys, or IDs are correct

Additional Features

• Rovo Dev: AI coding agent (beta) - acli rovodev -h
• Feedback: Submit feedback or report issues - acli feedback
• Configuration: Change settings - acli config -h

Notes

• acli works with Atlassian Cloud products
• Most list/search commands support --json and --csv output flags
• Work items were formerly called "issues" in Jira
• Some commands may require specific subscription levels or permissions
• Global OAuth (acli auth login) may not be available in all organizations
• Product-specific authentication (acli jira auth login) supports both OAuth and API tokens
• Bulk operations on multiple work items use --key "KEY-1,KEY-2" or --jql or --filter flags
• Use --yes flag to skip confirmation prompts for destructive/bulk operations