# Acli Jira

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

- Skill: `chenwei791129/acli-jira` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add chenwei791129/acli-jira`
- Raw SKILL.md: https://api.skillmd.com/api/skills/chenwei791129/acli-jira/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: chenwei791129 (https://skillmd.com/u/chenwei791129)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/chenwei791129/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:

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

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

```bash
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](references/commands.md#write-operations-use-with-caution).

## Custom Fields (Example Mappings)

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:

```bash
# 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

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

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

```bash
# 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

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

```bash
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](references/commands.md) for full command list and parameters.

## When to Use acli vs MCP

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

## Authentication

Check status: `acli jira auth status`

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