---
name: jira
description: Jira through the `acli` CLI. Use on any Jira issue key (e.g. ABC-123), JQL, or a request to view, search, create, edit, comment on, transition, assign, or link Jira work, or to download its attachments.
metadata:
  version: "0.2.0"
---

# Jira via acli

`acli jira workitem --help` and each subcommand's `--help` are the command reference; this page is the working agreement plus the gotchas `--help` doesn't confess. Paths to `references/` and `scripts/` are relative to this skill's directory.

## Working agreement

- Read with `--json` and summarise the fields. A search becomes a table of key, summary, status, assignee.
- `edit` and `transition` prompt for confirmation; pass `--yes`.
- Confirm a write with the issue key and the new value.
- On an auth failure, `acli jira auth status` lacks `✓ Authenticated`; ask the user to run `acli jira auth`, then retry.

## Commands

```
acli jira workitem view KEY-123 --json                   # --fields '*all' for description, comments, attachments
acli jira workitem search --jql "..." --json --limit 25   # --paginate for every result
acli jira workitem attachment list --key KEY-123 --json
acli jira workitem create --project ABC --type Task --summary "..." --description "..."
                                                          # --assignee "@me", --parent KEY-1, --label "a,b"
acli jira workitem edit --key KEY-123 --summary "..." --yes
acli jira workitem comment create --key KEY-123 --body "..."
acli jira workitem transition --key KEY-123 --status "In Progress" --yes
acli jira workitem assign --key KEY-123 --assignee "@me"
acli jira workitem link create --out KEY-123 --in KEY-456 --type Blocks
```

## Gotchas

- **Structured text goes through ADF.** Headings, code, bullets, bold, or links in a plain `--description`/`--body` string render as literal characters. Send them as ADF through `--description-file`/`--body-file`: [`references/adf.md`](references/adf.md) has the converter and the read-back check that proves it rendered.
- **Download attachments by id.** The `content` URL in `workitem view --json` points at an internal host that rejects API-token auth. `acli jira workitem attachment list --key KEY-123 --json` gives each attachment's `id`, `name`, and `size`; then:
  ```
  scripts/download-attachment.sh <attachment-id> <output-filename>
  ```
  The script authenticates with the raw API token in `$ACLI_TOKEN`, passed only through the environment, and exits with a message when it is missing. Then skip the download, finish everything else (attachment names and sizes, the issue URL), and tell the user: the token is optional and only needed for downloads; create one at https://id.atlassian.com/manage-profile/security/api-tokens and `export ACLI_TOKEN=...` in the shell, not in chat.
  Every image at once:
  ```
  acli jira workitem attachment list --key KEY-123 --json \
  | jq -r '.attachments[] | select(.name|test("\\.(png|jpe?g|gif|webp)$";"i")) | "\(.id)\t\(.name)"' \
  | while IFS=$'\t' read -r id name; do scripts/download-attachment.sh "$id" "$name"; done
  ```
- **Link types are project-specific.** `acli jira workitem link type` lists them; `link create --out KEY-123 --in KEY-456 --type "Blocks"` takes the name as Jira spells it.
- **Status names** in `transition` must match the exact name the project uses (`In Progress`, `In Review`).