Configuration
jira config init # interactive setup → ~/.config/jira-cli/config.toml
jira config validate # test connection
No env vars. JIRA_URL / JIRA_EMAIL / JIRA_API_TOKEN are intentionally ignored. Use CLI flags --url/--email/--token for one-off overrides.
Output Formats
--format table # default
--format json # array
--format jsonl # one object per line, auto-paginates all results
JSONL is preferred for scripting — pipe directly to jq.
CLI vs MCP
The CLI is the full interface. MCP tools are a subset.
Most resources and verbs are only available via CLI. MCP exposes the most common read/write operations but does not cover: bulk operations, boards, sprints, development info, goals, screens, automations, audit log, or raw API access.
Default to CLI (jira <resource> <verb>) for any operation not explicitly listed in an MCP tool. Use MCP when an agent needs structured tool call semantics or is already in an MCP session.
All resources follow: jira <resource> <verb> [args] [flags]
Resources: issues, projects, comments, attachments, worklogs, versions, components, filters, dashboards, issuetypes, statuses, issuelinks, remotelinks, development, plans, users, boards, sprints, fields, goals, screens, automations, auditlog
Read references/commands.md for exact flags and syntax for every resource.
Name Resolution
All parameters that previously required opaque IDs now accept human-readable names. Resolution is case-insensitive exact match; IDs pass through unchanged.
| Parameter | Accepts |
|---|---|
transition (issues transition) |
transition name or ID |
user / accountId / assigneeAccountId / leadAccountId |
email, display name, or account ID |
fieldId (fields commands) |
field name (e.g. "Story Points") or ID (e.g. customfield_12497) |
--field "Name=Value" / customFields on create & update |
field name as key; value resolved by type (see below) |
Custom field value resolution (--field on CLI, customFields on MCP):
Keys are resolved from field name → customfield_*. Values are resolved by field type:
option names → {value}, user names/emails → accountId, sprint names → sprint ID (all boards searched), numbers parsed from strings. Unknown types pass through; Jira surfaces errors.
Sprint name lookup searches all boards — may be slow on large instances. Error on non-unique sprint names across boards.
Non-unique match errors. If a name matches 2+ candidates, the call fails with a list of all matches and their IDs. Use an ID to be precise.
User resolution fallback. If searchUsers(query) returns no results, the value is treated as a raw account ID. Empty string always passes through (used to unassign).
Critical Gotchas
204 empty response ≠ error. Mutating operations (assign, transition, delete) return HTTP 204. The MCP layer may surface this as an error. Always verify with a GET:
mcp__jira__jira_issues_assign(key="PROJ-1", user="alice@example.com")
issue = mcp__jira__jira_issues_get(key="PROJ-1") # verify assignee
Development API needs numeric ID. jira development * and mcp__jira__jira_development_summary require the internal numeric issue ID, not the key:
ISSUE_ID=$(jira issues get PROJ-123 --format json | jq -r '.id')
jira development pull-requests $ISSUE_ID --application-type github
MCP returns minimal fields by default (~70% token reduction). Use fields param to request additional data.
Goals field cannot be set via REST API. customfield_10025 returns 204 No Content but the field is never updated — /editmeta exposes allowedValues: []. Known bug: JRACLOUD-97866. Link issues to goals through the Jira UI only.
Issue Sync (Markdown ↔ Jira)
Keep a local .md file in sync with a Jira issue description — same pattern as gspace docs sync.
jira issues pull PROJ-123 [file.md] # download description → local file (default: PROJ-123.md)
jira issues sync file.md # push local file → Jira description
File format — YAML frontmatter + markdown body:
---
jira:
key: PROJ-123
url: https://yourorg.atlassian.net/browse/PROJ-123
updated: "2026-05-13T08:00:00.000+0000"
summary: "Issue title"
duedate: 2026-12-31 # or ~ if unset
sprint: Sprint 42 # or ~ if unset
fix_versions:
- v2.0
assignee: Josh Lane # or ~ if unset
custom_fields: # editable custom fields only (filtered by edit screen)
strategic_alignment: 3
problem_classification: Operational Risk
---
Description body goes here.
Conflict detection: sync compares jira.updated against the remote timestamp. If remote is more than 60s newer, aborts with a message and suggests pull to refresh.
File locking: both commands acquire file.md.lock before any I/O. Stale locks (>60s) are overridden with a warning.
Local images:  in the markdown body is base64-encoded and embedded in the ADF on sync. On pull, base64 data URLs are decoded to ./images/{KEY}-img-{n}.png and referenced as relative paths.
What syncs: description, summary, duedate, sprint (name), fix_versions (list of version names), assignee (display name, ~ to unassign), and any editable custom fields in the custom_fields: block. Custom field keys are snake_case; values are pushed via the fields cache (direct field ID lookup — no name-ambiguity errors). Calculated/view-only fields may appear in custom_fields: if the Jira instance doesn't configure a separate edit screen; writes to such fields are silently ignored by Jira.
Mermaid diagrams: ```mermaid ``` blocks are automatically rendered to PNG via mmdc (Mermaid CLI) and uploaded as attachments. The Jira description shows the rendered image; the mermaid source block is preserved only in the local file. Install mmdc with npm install -g @mermaid-js/mermaid-cli. If mmdc is absent or fails, the sync completes without error and the diagram is omitted from Jira.
Known limitations:
codemark cannot be combined with other marks (bold/italic) — ADF spec constraint, Jira rejects it- Round-trip introduces minor whitespace differences in tables and blockquotes
- Nested bold+italic (
**bold _italic_**) emits redundant**on pull — cosmetic, content preserved pulldoes not restore mermaid source blocks — local file is authoritative for mermaid content
Linking Documents to Issues
Always use remote links, never file attachments. File attachments do not render correctly in Jira — they appear as raw downloads. Remote links render as clickable chips with the correct application icon.
Google Drive URLs are auto-detected: Docs, Sheets, and Folders each get the correct icon. Non-Google URLs are linked as generic web links.
Never use jira attachments upload for documents — use jira remotelinks add instead. See references/commands.md for syntax.
Common Patterns
# Search + stream to jq
jira issues search "project = PROJ AND status = Open" --format jsonl | jq '.fields.status.name'
# Count by status
jira issues search "project = PROJ" --format jsonl \
| jq -r '.fields.status.name' | sort | uniq -c | sort -rn
# Extract issue link edges (for dependency graphs)
jira issues search "issuelinktype is not EMPTY" --fields issuelinks --format jsonl \
| jq -r '.key as $k | .fields.issuelinks[]? |
if .outwardIssue then "\($k),\(.type.outward),\(.outwardIssue.key)"
else "\(.inwardIssue.key),\(.type.inward),\($k)" end'
# List active sprint issues on a board
BOARD_ID=$(jira boards list --format jsonl | jq -r 'select(.name=="My Board") | .id')
jira sprints list --board $BOARD_ID --state active --format jsonl \
| jq -r '.id' \
| xargs -I{} jira issues search "sprint = {}" --format jsonl
JQL Quick Reference
assignee = currentUser() AND status != Done
updated >= -7d ORDER BY updated DESC
type = Bug AND priority in (Highest, High)
sprint in openSprints() AND project = PROJ
issuelinktype is not EMPTY AND project = PROJ
Goals (jira goals CLI — not available via MCP)
Goals use a separate jira goals command group backed by the Atlassian GraphQL API — not Jira REST. Goal type ARIs are workspace-specific; run jira goals list-types to get them.
Hierarchy: Two levels only: GOAL → SUCCESS_MEASURE. A SUCCESS_MEASURE cannot have children.
See references/commands.md for full goal command syntax.
Raw API Access
jira api GET "/rest/api/3/issue/PROJ-123?fields=summary,status"
jira api POST "/rest/api/3/search/jql" --data '{"jql":"project=PROJ","fields":["summary"]}'
jira api PUT "/rest/api/3/issue/PROJ-123" --data '{"fields":{"summary":"New title"}}'
Gotcha: /rest/api/3/search is removed — use POST /rest/api/3/search/jql with body {"jql":"...","fields":[...],"maxResults":50}.