Atlassian CLI (acli) for Jira operations. Use when working with Jira issues via command line - viewing tickets ("view PROJ-123", "show ticket"), searching with JQL ("find issues", "search Jira"), listing projects/boards/sprints, viewing comments/attachments/links, or any Jira query that benefits from CLI output. Prefer acli over MCP tools for structured JSON output and complex JQL queries.
Use acli jira for Jira Cloud operations via command line.
The text/table output format has bugs. Always add --json to commands for reliable output:
# CORRECT - always use --json
acli jira workitem view KEY-123 --json
acli jira workitem search --jql "project = PROJ" --json
# INCORRECT - will often fail with "unexpected error"
acli jira workitem view KEY-123
acli jira workitem search --jql "project = PROJ" --csv
acli has intermittent "unexpected error" failures (~60-80% failure rate). This is an API/network issue, not syntax-related. Retry the command if it fails:
# If this fails, just run it again
acli jira workitem view PROJ-123 --json
# Error: unexpected error, trace id: xxx <-- retry!
For critical operations, consider using MCP tools which are more reliable.
Common custom field mappings for JSM tickets:
| Field Name | Custom Field ID | Example Value |
|---|---|---|
| Related Project(s) | customfield_10735 | ["My-Project"] |
| Root Cause | customfield_10536 | Text description |
| Root Cause Category | customfield_10560 | "Coding Bug" |
| Resolution | customfield_11506 | Text description |
| Impact Summary | customfield_11371 | Markdown table |
| Severity | customfield_10530 | "High", "Medium", "Low" |
| Reporter Type | customfield_10531 | "Monitoring System", "CS" |
Limitation: acli --fields flag does NOT work reliably with custom fields. For custom fields, use MCP tool instead:
# This will FAIL
acli jira workitem view PROJ-123 --fields "customfield_10536" --json
# Use MCP tool instead (fields: "*all")
mcp__atlassian__jira_get_issue(issue_key="PROJ-123", fields="*all")
acli jira workitem view PROJ-123 --json
Default fields: key,issuetype,summary,status,assignee,description
Note: --fields '*navigable' often fails. Use default fields or MCP tool for custom fields.
# Basic project search
acli jira workitem search --jql "project = PROJ" --limit 10 --json
# With pagination for large results
acli jira workitem search --jql "project = PROJ" --paginate --json
JQL Limitations: Some JQL queries fail. If key = PROJ-123 fails, use workitem view instead:
# This may fail
acli jira workitem search --jql "key = PROJ-123" --json
# Use this instead
acli jira workitem view PROJ-123 --json
acli jira workitem comment list --key PROJ-123 --json
acli jira workitem attachment list --key PROJ-123 --json
acli jira workitem link list --key PROJ-123 --json
acli jira project view --key PROJ --json
acli jira board search --limit 10 --json
acli jira board list-sprints --id 123 --json
See references/commands.md for full command list and parameters.
| Use Case | Recommended Tool |
|---|---|
| View basic ticket info | acli jira workitem view |
| Search with simple JQL | acli jira workitem search |
| List projects/boards/sprints | acli commands |
| Get custom fields (Root Cause, etc.) | mcp__atlassian__jira_get_issue with fields="*all" |
| Complex JQL with filters | MCP tool |
Check status: acli jira auth status
Authentication is configured outside this skill. If auth fails, verify API token configuration.