Acli Jira

Atlassian CLI (acli) for Jira

Use acli jira for Jira Cloud operations via command line.

Critical: Always Use --json Flag

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

Intermittent API Errors

acli may return intermittent unexpected error failures. For read-only commands, retry with a bounded attempt count:

# If this fails with a transient error, retry it a few times.
acli jira workitem view PROJ-123 --json

Do not blindly retry non-idempotent writes such as workitem create: the server may have completed the request even when the CLI lost the response. Query Jira for the expected result first, then retry only when it was not created. For transitions, assignments, and edits, inspect the current field value before retrying.

For critical operations, consider using MCP tools when they are more reliable.

Confirm Write-command Syntax

The write subcommands use flag-based selectors, and their flags may differ between acli releases. Before an unfamiliar or bulk write, check the installed command:

acli jira workitem transition --help
acli jira workitem assign --help
acli jira workitem edit --help

Current syntax uses --key/--jql plus --status for transitions; it does not use a positional key with --transition. See references/commands.md.

Custom Fields (Example Mappings)

Common custom field mappings for JSM tickets:

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

Common Operations

View a Ticket

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.

Search with JQL

# 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

Comments, Attachments, Links

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

Projects and Boards

acli jira project view --key PROJ --json
acli jira board search --limit 10 --json
acli jira board list-sprints --id 123 --json

Command Reference

See references/commands.md for full command list and parameters.

When to Use acli vs MCP

Authentication

Check status: acli jira auth status

Authentication is configured outside this skill. If auth fails, verify API token configuration.