gh-xdg-xdg-claude-jira-cli/skills/jira-cli/reference/jira-cli-reference.md

jira-cli Detailed Reference

Assumptions: Already installed/configured, JIRA_API_TOKEN set, jira init complete

Project flag: Always use -p PROJ to specify project explicitly (don't rely on defaults)

---

Core Workflow: Working on Issue

# User: "Work on PROJ-123"
jira issue view -p PROJ PROJ-123                          # Read requirements
jira issue assign PROJ-123 $(jira me)                     # Assign to user
jira issue move PROJ-123 "In Progress"                    # Update status
# ... implement code ...
jira issue comment add PROJ-123 "Fixed in $(git rev-parse --short HEAD)"
jira issue move PROJ-123 "Done"                           # Close

---

Command Syntax by Intent

Query Issues

By filters:

jira issue list -p PROJ -tBug -aCurrentUser -s"To Do"     # Type, assignee, status
jira issue list -p PROJ -yHigh -lbackend --created week   # Priority, label, date

By JQL (complex queries):

jira issue list -p PROJ --jql 'assignee=currentUser() AND status!="Done"'
jira issue list -p PROJ --jql 'priority IN (High,Critical) AND created >= -7d'

Common patterns:

• My bugs: jira issue list -p PROJ -tBug -aCurrentUser
• High priority work: jira issue list -p PROJ -yHigh -s"To Do"
• Recent activity: jira issue list -p PROJ -aCurrentUser --updated -1d

View Issue

jira issue view -p PROJ PROJ-123                          # Basic view
jira issue view -p PROJ PROJ-123 --comments 50            # With comments
jira issue view -p PROJ PROJ-123 --raw                    # JSON output
jira open PROJ-123                                        # Open in browser

Create Issue

jira issue create -p PROJ -tBug -s"Summary" -yHigh -lbackend
jira issue create -p PROJ -tStory -s"Feature name"

Update Issue

jira issue assign PROJ-123 $(jira me)                     # Assign to self
jira issue assign PROJ-123 "user@example.com"             # Assign to user
jira issue move PROJ-123 "In Progress"                    # Change status
jira issue comment add PROJ-123 "Comment text"            # Add comment
jira issue edit -p PROJ PROJ-123 -yHigh -lurgent          # Edit priority/labels

---

Efficient Data Extraction

Principle: Extract only needed fields to minimize context.

# Get single field via jq
jira issue view -p PROJ PROJ-123 --raw | jq -r '.fields.status.name'
jira issue view -p PROJ PROJ-123 --raw | jq -r '.fields.assignee.displayName'

# Get specific columns only
jira issue list -p PROJ --plain --no-headers --columns KEY
jira issue list -p PROJ --plain --columns KEY,STATUS,ASSIGNEE

# Check existence
jira issue view -p PROJ PROJ-123 --plain > /dev/null 2>&1 && echo "exists"

---

JQL Reference

Structure: jira issue list -p PROJ --jql 'FIELD OPERATOR VALUE'

Operators: =, !=, IN, >, <, >=, <=

Functions:

• currentUser() - Current logged-in user
• openSprints() - Active sprints
• startOfWeek(), startOfDay() - Date functions

Date formats:

• Relative: -7d, -2w, -1m
• Absolute: "2023-12-01"

Examples:

# Multiple conditions
jira issue list -p PROJ --jql 'project=PROJ AND assignee=currentUser() AND status!="Done"'

# Date ranges
jira issue list -p PROJ --jql 'created >= -7d AND updated >= startOfWeek()'

# IN operator
jira issue list -p PROJ --jql 'status IN ("To Do","In Progress")'

---

Output Formats

For display: Default table format For parsing: --plain --no-headers --columns KEY For extraction: --raw with jq

# Table (default)
jira issue list -p PROJ

# Plain text for parsing
jira issue list -p PROJ --plain --no-headers --columns KEY

# JSON for field extraction
jira issue view -p PROJ PROJ-123 --raw | jq -r '.fields.summary'

---

Filter Flags Reference

Flag	Purpose	Example
-t	Type	-tBug, -tStory, -tTask
-s	Status	-s"To Do", -s"In Progress"
-y	Priority	-yHigh, -yMedium, -yLow
-a	Assignee	-aCurrentUser, -a"user@example.com"
-l	Label	-lbackend, -lurgent,critical
--created	Created date	--created today, --created week, --created 2023-12-01
--updated	Updated date	--updated -7d
--jql	Raw JQL query	--jql 'custom query'

---

User Intent → Command Mapping

User Says	Command
"Work on PROJ-123"	jira issue view -p PROJ PROJ-123
"What bugs do I have?"	jira issue list -p PROJ -tBug -aCurrentUser
"What should I work on?"	jira issue list -p PROJ -yHigh -s"To Do"
"Create bug for X"	jira issue create -p PROJ -tBug -s"X"
"Close PROJ-123"	jira issue move PROJ-123 "Done"
"Add comment to PROJ-123"	jira issue comment add PROJ-123 "text"
"What did I work on yesterday?"	jira issue list -p PROJ -aCurrentUser --updated -1d

---

Best Practices

1. Always specify project: Use -p PROJ flag explicitly
2. Extract minimal data: Use --raw | jq for specific fields instead of reading full issue
3. Filter before reading: Narrow with queries, then read details
4. Use plain output for scripts: --plain --no-headers --columns KEY
5. Proactive updates: After code changes, offer to add commits/close issues
6. Rate limits: Add sleep 0.5 between bulk operations

---

Troubleshooting

Auth errors: Check echo $JIRA_API_TOKEN and cat ~/.config/.jira/.config.yml

Issue not found: Verify project key correct: jira issue view -p PROJ PROJ-123 --plain

Rate limits: Add delays between bulk operations, use more specific queries