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

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=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

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`

jira

Jira

Wiki Markup Syntax