---

name: jira description: > Jira integration via jira-cli. Use when: searching issues, viewing issue details, creating issues, transitioning status, adding comments, logging work, managing sprints, managing boards, linking issues, formatting descriptions with wiki markup, converting Markdown to Jira format, or using bug/feature templates. Keywords: jira issue, jira ticket, jira format, wiki markup, jira syntax. Requires jira-cli installed via brew install jira-cli.

Jira

Jira operations via jira-cli with wiki markup formatting.

Wiki Markup Syntax

Jira uses wiki markup, NOT Markdown. Use this reference when writing descriptions or comments:

See references/syntax-reference.md for complete documentation.

Prerequisites

Copy# Install jira-cli
brew install jira-cli

# Configure (interactive)
jira init

# Verify setup
jira serverinfo
jira me

Quick Reference

Search & List Issues

Copy# All issues in project
jira issue list -p PROJ

# With JQL query
jira issue list -q "project = PROJ AND status = 'In Progress'"

# Filter by status, type, priority, assignee
jira issue list -p PROJ -s "To Do" -t Bug -yHigh -a "user@example.com"

# Unassigned issues
jira issue list -p PROJ -ax

# Recently created (last 7 days)
jira issue list -p PROJ --created -7d

# Issues I'm watching
jira issue list -w

# Plain output for scripting
jira issue list -p PROJ --plain --columns KEY,SUMMARY,STATUS --no-truncate

# CSV export
jira issue list -p PROJ --csv > issues.csv

# JSON output
jira issue list -p PROJ --raw

View Issue

Copy# Basic view
jira issue view PROJ-123

# With comments
jira issue view PROJ-123 --comments 5

# Open in browser
jira open PROJ-123

Create Issue

Copy# Basic creation
jira issue create -p PROJ -t Task -s "Fix login bug"

# With description and priority
jira issue create -p PROJ -t Bug -s "Login fails" -b "h2. Steps to Reproduce
# Navigate to login
# Enter credentials
# Click submit

h2. Expected
Login succeeds

h2. Actual
500 error" -yHigh

# With labels and components
jira issue create -p PROJ -t Story -s "New feature" -l backend -l "high prio" -C "API"

# Sub-task (requires parent)
jira issue create -p PROJ -t Sub-task -s "Subtask" -P PROJ-100

# With custom fields
jira issue create -p PROJ -t Story -s "Feature" --custom "customfield_10001=value"

# Non-interactive (skip prompts)
jira issue create -p PROJ -t Task -s "Quick task" --no-input

Edit Issue

Copy# Edit summary
jira issue edit PROJ-123 -s "New summary"

# Edit description
jira issue edit PROJ-123 -b "Updated description"

# Change priority
jira issue edit PROJ-123 -yHigh

# Add labels
jira issue edit PROJ-123 -l newlabel

Assign Issue

Copy# Assign to user
jira issue assign PROJ-123 "user@example.com"

# Assign to me
jira issue assign PROJ-123 $(jira me)

# Default assignee
jira issue assign PROJ-123 default

# Unassign
jira issue assign PROJ-123 x

Transition (Move) Issue

Copy# Move to status
jira issue move PROJ-123 "In Progress"
jira issue move PROJ-123 "Done"

# With resolution
jira issue move PROJ-123 "Done" -R"Fixed"

# Assign during transition
jira issue move PROJ-123 "In Progress" -a$(jira me)

Comments

Copy# Add comment
jira issue comment add PROJ-123 "Fixed in commit abc123"

# Add comment from file
jira issue comment add PROJ-123 -T comment.txt

# List comments (via issue view)
jira issue view PROJ-123 --comments 10

Worklogs (Time Tracking)

Copy# Log time
jira issue worklog add PROJ-123 2h
jira issue worklog add PROJ-123 "1h 30m"

# With comment
jira issue worklog add PROJ-123 2h --comment "Implemented feature X"

Issue Links

Copy# Link two issues
jira issue link PROJ-123 PROJ-456 "Blocks"
jira issue link PROJ-123 PROJ-456 "Relates"
jira issue link PROJ-123 PROJ-456 "Duplicate"

# Unlink issues
jira issue unlink PROJ-123 PROJ-456

Sprints

Copy# List sprints for a board
jira sprint list BOARD_ID

# Active sprints only
jira sprint list BOARD_ID --state active

# Add issue to sprint
jira sprint add SPRINT_ID PROJ-123

# Current sprint issues
jira sprint list BOARD_ID --current

Boards

Copy# List boards for project
jira board list -p PROJ

# Get board ID, then use for sprint operations

Output Formats

Templates

Use these templates for well-structured issues:

• Bug Report: templates/bug-report-template.md - Environment, Steps to Reproduce, Expected/Actual, Error Messages
• Feature Request: templates/feature-request-template.md - Overview, User Stories, Acceptance Criteria, Technical Approach

Syntax Validation

Validate wiki markup before submitting:

Copyscripts/validate-jira-syntax.sh path/to/content.txt

Checks for common Markdown mistakes and suggests Jira equivalents.

Field Discovery

jira-cli cannot list available fields. Use the included Python script:

Copy# Search for fields by name
uv run scripts/jira-fields.py search "story points"
uv run scripts/jira-fields.py search sprint

# List all custom fields
uv run scripts/jira-fields.py list --type custom

# JSON output
uv run scripts/jira-fields.py --json search "epic"

Requires auth via ~/.env.jira:

CopyJIRA_URL=https://company.atlassian.net
JIRA_USERNAME=your-email@example.com
JIRA_API_TOKEN=your-api-token

Common Workflows

Find and work on a backlog item

Copy# Find high priority backlog items
jira issue list -p PROJ -s Backlog -yHigh --plain

# Pick one and start working
jira issue move PROJ-123 "In Progress" -a$(jira me)

# Log some work
jira issue worklog add PROJ-123 2h --comment "Started implementation"

# Add a comment
jira issue comment add PROJ-123 "WIP: implementing feature X"

# Complete the work
jira issue move PROJ-123 "Done" -R"Fixed"

Sprint planning

Copy# Find the board
jira board list -p PROJ

# List sprints
jira sprint list BOARD_ID

# Get backlog items ready for sprint
jira issue list -p PROJ -s Backlog --plain --columns KEY,SUMMARY,PRIORITY

# Add issues to sprint
jira sprint add SPRINT_ID PROJ-100 PROJ-101 PROJ-102

References

• Command Reference - Quick lookup table
• JQL Quick Reference - Query syntax
• Backlog Quick Wins - Finding actionable items
• Syntax Reference - Complete wiki markup documentation
• jira-cli GitHub - Full documentation
• Official Jira Wiki Markup