---
name: jira
description: Read Jira tickets, search them with JQL, and comment on them through Jira's REST API. Use when the user mentions a Jira key like PROJ-123, asks about their tickets, or wants to start work from a ticket.
---

# Jira through the REST API

Talk to Jira with `curl`. Credentials come from environment variables: never print them, echo
them, write them to a file, or ask the user to paste a token into the chat.

## Credentials

- `JIRA_URL`: the site, `https://optumfinancial.atlassian.net`, with no trailing slash
- `JIRA_EMAIL`: the email the user signs in to Jira with
- `JIRA_API_TOKEN`: their API token

Check which are set without revealing them:

```bash
for v in JIRA_URL JIRA_EMAIL JIRA_API_TOKEN; do printenv "$v" >/dev/null && echo "$v set" || echo "$v missing"; done
```

If they're missing, tell the user where to add them, then to start a new session:

- Claude desktop app: start a new session, and before sending anything, hover the **Local** dropdown
  in the prompt area and click its gear icon. It only appears at the start of a session.
- Terminal: `export` them in the shell profile

Authenticate every request with `-u "$JIRA_EMAIL:$JIRA_API_TOKEN"`.

## Read a ticket

```bash
curl -sS -u "$JIRA_EMAIL:$JIRA_API_TOKEN" -H "Accept: application/json" \
  "$JIRA_URL/rest/api/2/issue/PROJ-123?fields=summary,status,issuetype,priority,assignee,labels,description,comment"
```

Summarise the summary, status, description, acceptance criteria and the latest comments. Don't
dump the raw JSON on the user.

## Search with JQL

```bash
curl -sS -G -u "$JIRA_EMAIL:$JIRA_API_TOKEN" -H "Accept: application/json" \
  "$JIRA_URL/rest/api/3/search/jql" \
  --data-urlencode "jql=assignee = currentUser() AND statusCategory != Done ORDER BY updated DESC" \
  --data-urlencode "fields=summary,status,priority" \
  --data-urlencode "maxResults=20"
```

## Comment on a ticket

Show the user the exact comment first and wait for a clear yes. Then send it, with the body in a
heredoc so quotes and newlines survive:

```bash
curl -sS -X POST -u "$JIRA_EMAIL:$JIRA_API_TOKEN" -H "Content-Type: application/json" \
  "$JIRA_URL/rest/api/2/issue/PROJ-123/comment" --data @- <<'EOF'
{"body": "The comment text"}
EOF
```

## Anything else

For transitions, field edits or new tickets, say exactly what you would send and ask before
sending it. Never delete anything.

## When a request fails

- `401`: the token is wrong or expired. Ask the user to create a new one.
- `403`: the user has no permission on that project.
- `404`: the key is wrong, or the user can't see that ticket.

Don't retry a write that failed; report it.