jira

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:

Jira Syntax	Purpose	NOT this (Markdown)
h2. Title	Heading	## Title
*bold*	Bold	**bold**
_italic_	Italic	*italic*
{{code}}	Inline code	`code`
{code:java}...{code}	Code block	```java ```
[text|url]	Link	[text](url)
[PROJ-123]	Issue link	-
[~username]	User mention	@username
* item	Bullet list	- item
# item	Numbered list (see warning)	1. item
||Header||	Table header	|Header|

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

Troubleshooting Auth

If jira me fails with a token error, the token likely exists but isn't visible in the current shell. Check these locations before asking the user to generate a new one:

# 1. Is the env var set in this shell?
echo $JIRA_API_TOKEN

# 2. Is direnv loading it from a shared env file?
grep -r "JIRA_API_TOKEN" ~/.config/direnv/envrc.d/ 2>/dev/null

# 3. Is it in a project-specific .envrc that hasn't been sourced here?
grep -rl "JIRA" ~/Code/**/.envrc 2>/dev/null

# 4. Is there a dedicated env file for the Ruby scripts?
cat ~/.env.jira 2>/dev/null

# 5. Check the jira-cli config itself
cat ~/.config/.jira/.config.yml | head -10

Common fix: if the token is loaded via direnv in another project, add a .envrc to the current project that sources the same shared file (e.g. source_env ~/.config/direnv/envrc.d/envato.sh), then run direnv allow.

Switching Projects and Boards

jira-cli stores its default project and board in ~/.config/.jira/.config.yml. When switching teams or projects, update these fields:

board:
    id: 2469              # Board ID (find via: jira board list -p PROJ)
    name: My Team Board   # Display name
    type: kanban           # kanban or scrum
# ...
project:
    key: EN               # Project key
    type: classic          # classic or next-gen

You can also override the project per-command with -p PROJECT without changing the config.

Quick Reference

Operation	Command
Search issues	jira issue list -q "JQL"
View issue	jira issue view KEY
Create issue	jira issue create -t Type -s "Summary"
Edit issue	jira issue edit KEY
Assign issue	jira issue assign KEY USER
Transition	jira issue move KEY "Status"
Add comment	jira issue comment add KEY "text"
Log work	jira issue worklog add KEY TIME
Link issues	jira issue link KEY1 KEY2 TYPE
List sprints	jira sprint list BOARD_ID
List boards	jira board list -p PROJECT
Current user	jira me
Find fields	ruby scripts/jira_fields.rb search TERM

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 "[e-mail]"

# 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 "[e-mail]"

# 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

Note: jira board list does not support --plain or other output flags. It always outputs a simple table.

Output Formats

Flag	Description
(default)	Interactive TUI mode
--plain	Plain text table
--csv	CSV format
--raw	Raw JSON
--no-truncate	Show full field values
--columns KEY,SUMMARY,...	Select columns
--no-headers	Hide table headers

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 environment variables. The script checks ~/.env.jira first, then falls back to env vars (JIRA_URL, JIRA_USERNAME, JIRA_API_TOKEN). If you already have these set via direnv, no extra file is needed.

Example ~/.env.jira (only if not using direnv):

JIRA_URL=https://company.atlassian.net
JIRA_USERNAME=[e-mail]
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