jira

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