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:

Wiki Markup Pitfalls (Jira Cloud):

• # item numbered lists often render as h1 headings in Jira Cloud. Prefer * item bullets instead.
• * *bold text* breaks bullet lists — the bold * collides with the bullet *. Avoid bold as the first word of a bullet, or use _italic_ instead.
• {code} blocks may escape parentheses and special characters when submitted via CLI. Use {noformat} or nested bullets for simple structured text.

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

Prerequisites

# Install jira-cli
brew install jira-cli

# Configure (interactive)
jira init

# Verify setup
jira serverinfo
jira me

Quick Reference

Search & List Issues

# 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

# 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

# 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

# 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

# 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

# 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

# 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)

# 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

# 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

# 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

# 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:

scripts/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 Ruby script:

# Search for fields by name
ruby scripts/jira_fields.rb search "story points"
ruby scripts/jira_fields.rb search sprint

# List all custom fields
ruby scripts/jira_fields.rb list --type custom

# JSON output
ruby scripts/jira_fields.rb search "epic" --json

Requires auth via ~/.env.jira:

JIRA_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

# 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

# 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