name: jira-cli
description: Interact with Jira using the jira-cli command-line tool to manage issues, sprints, epics, and boards. Use when working with Jira tickets, sprint planning, issue tracking, or when the user mentions Jira, tickets, sprints, epics, or issue management.
compatibility: Requires jira-cli installed and configured (jira init)

Jira CLI

Use jira-cli to interact with Jira from the command line.

Prerequisites

• Jira CLI installed and configured with jira init
• Config: ~/.config/.jira/.config.yml (override with JIRA_CONFIG_FILE)

Critical Usage Patterns

Always use --plain for listing and --no-input for creation to avoid interactive mode:

jira issue list --plain              # ✓ Parseable output
jira issue create --no-input         # ✓ Skip prompts
jira issue view KEY --raw            # ✓ JSON output

Creating Issues: Template-First Workflow

IMPORTANT: Always use a template file for issue creation to avoid shell escaping and formatting issues with bullets, quotes, and special characters.

Recommended Workflow

1. Research style first - Query recent issues of the same type to match team conventions:
   bash jira issue list -p PROJECT -t"Spike" --created month --plain --columns key,summary,status jira issue view KEY --plain # View a few to understand description style

2. Draft in a template file - Create /tmp/issue-template.md with the description body only (no frontmatter needed). Let user review and edit before proceeding.

3. Create using --template - This avoids all shell escaping issues:
   bash jira issue create -p PROJECT -t TYPE -s "Summary" -P "PARENT-KEY" \ --template /tmp/issue-template.md --no-input

Template File Format

The template file contains only the description body in Jira-flavored markdown:

As a [role], I want [what], so that [benefit].

* First action item
  - Sub-item with detail
  - Another sub-item
* Second action item
* Third action item

Quick Create (simple descriptions only)

For single-line or very simple descriptions without special characters:

jira issue create -p PROJECT -t Task -s "Summary" -b "Simple description" --no-input

Common Options

-p PROJECT          # Project key
-t TYPE             # Issue type (Bug, Story, Task, Spike, etc.)
-s "Summary"        # Issue title
-P "PARENT-KEY"     # Parent epic or issue
-y PRIORITY         # Priority (High, Critical, etc.)
-a "user@email"     # Assignee
-l label            # Labels (repeat for multiple)
--template FILE     # Description from file (RECOMMENDED)
--no-input          # Skip interactive prompts
--web               # Open in browser after creation

Listing and Viewing Issues

# View single issue
jira issue view KEY --plain
jira issue view KEY --raw                   # JSON output
jira issue view KEY --comments 10           # Include comments

# List with filters
jira issue list -p PROJECT --plain
jira issue list -t TYPE --plain             # By type
jira issue list -s "In Progress" --plain    # By status
jira issue list -a "user@email" --plain     # By assignee
jira issue list -y High --plain             # By priority
jira issue list -P "PARENT-KEY" --plain     # By parent
jira issue list -l label --plain            # By label

# Date filters
jira issue list --created month --plain
jira issue list --updated "-7d" --plain

# Custom columns and output
jira issue list --plain --columns key,summary,status,assignee

# JQL for complex queries
jira issue list -q "project = MPD AND status = 'In Progress'" --plain

Updating Issues

jira issue edit KEY -s "New summary"
jira issue edit KEY --priority Critical
jira issue edit KEY --assignee "user@email"
jira issue edit KEY --label newlabel
jira issue assign KEY "user@email"
jira issue assign KEY -x                    # Unassign
jira issue move KEY "In Progress"           # Transition status
jira issue comment add KEY -m "Comment"
jira issue link KEY1 KEY2 "relates to"

Sprints and Epics

# Sprints
jira sprint list --table --plain
jira sprint list --state active --plain
jira sprint list --current --plain          # Current sprint issues

# Epics
jira epic list --table --plain
jira epic list EPIC-KEY --plain             # Issues in epic
jira epic add EPIC-KEY ISSUE-KEY            # Add issue to epic

Other Operations

jira open KEY                               # Open in browser
jira me --plain                             # Current user
jira project list --plain
jira board list --plain

JQL Quick Reference

assignee = currentUser()
assignee is EMPTY
status not in ("Done", "Closed")
updated >= -7d
project = MPD AND priority in (High, Highest)
parent = EPIC-KEY
ORDER BY created DESC

Notes

• Default pagination is 100 items; use --paginate N for more
• Custom fields require field ID: --custom field-id=value
• Debug with jira --debug