Jira CLI

Procedural guide for using the jira CLI tool (ankitpokhrel/jira-cli) non-interactively from Claude Code.

Critical Rules

1. Always use --no-input to suppress interactive prompts (except issue link which does not support it)
2. Never use -b for long descriptions — it causes the CLI to hang. Use file + pipe instead
3. --template flag only works on create and comment add, not on edit
4. The CLI uses a markdown-to-ADF parser — see references/formatting.md for what works and what breaks
5. Pipe from stdin for descriptions longer than 2-3 lines
6. Avoid special characters in descriptions — parentheses (), angle brackets <>, underscores _, and arrows -> get escaped by the markdown parser inside code blocks

Quick Reference

Check auth

jira me

Create issue

# Short description
jira issue create -p PROJECT -t Task -s "Summary" -y High --no-input

# Long description (ALWAYS use this pattern)
cat /tmp/jira-body.md | jira issue create -p PROJECT -t Task -s "Summary" -y High --template - --no-input

View issue

jira issue view KEY --plain        # Human-readable
jira issue view KEY --raw          # JSON for scripting

Edit issue

jira issue edit KEY -s "New summary" --no-input
echo "New description" | jira issue edit KEY --no-input    # Replaces description entirely

List issues

jira issue list --plain                                    # All issues
jira issue list -s "In Progress" --plain                   # By status
jira issue list -q "assignee = currentUser()" --plain      # Custom JQL

Transition issue

jira issue move KEY "In Progress"
jira issue move KEY Done --comment "Completed in PR #123"

Sprint operations

jira sprint list --state active              # Active sprints
jira sprint list --current --plain           # Issues in current sprint
jira sprint add SPRINT_ID KEY1 KEY2          # Add issues to sprint

For the full command reference, see references/commands.md.

Long Description Workflow

For any description longer than 2-3 lines, ALWAYS write to a temp file and pipe.

Use the hybrid formatting that survives the CLI's markdown-to-ADF conversion:

• h2. headings (wiki syntax — these survive)
• ||Header|| tables (wiki syntax — these survive)
• *bold* for emphasis
• * item for bullet lists (NOT # for numbered lists)
• Triple backtick fenced code blocks (NOT {code} or {noformat})
• Plain text for issue keys like SPRINT-123 (auto-linked by Jira)
• Avoid (), <>, _, -> inside code blocks (they get escaped)

# 1. Write description using hybrid formatting
cat > /tmp/jira-body.md << 'DESCRIPTION'
h2. Context

Description content here...

h2. Acceptance Criteria

* Criterion one
* Criterion two

h2. Technical Notes

code goes here with no special chars

DESCRIPTION

# 2a. Create issue
cat /tmp/jira-body.md | jira issue create -p PROJECT -t Task -s "Summary" -y High --template - --no-input

# 2b. OR edit existing issue (no --template flag)
cat /tmp/jira-body.md | jira issue edit KEY --no-input

# 3. Clean up
rm /tmp/jira-body.md

See references/formatting.md for the complete guide on what renders correctly.

Common Gotchas

Pitfall	Cause	Solution
-b with long content hangs	CLI buffer issue	Use file + pipe with --template -
--template on edit	Not a valid flag for edit	Pipe from stdin instead
# renders as heading	CLI's markdown parser interprets # as heading	Use * bullet lists or tables with numbered rows
{code:sql}...{code} content mangled	Markdown parser escapes (), _, -> inside wiki code blocks	Use triple backtick fenced code blocks instead
{noformat} content escaped	Same markdown parser issue	Use triple backtick fenced code blocks
{{inline code}} broken	Wiki syntax not recognized by markdown parser	Avoid or use plain text
[text|url] link broken	Wiki link syntax conflicts with markdown parser	Write ticket keys as plain text (auto-linked) or use markdown [text](url)
--no-input on issue link	Flag not supported on this subcommand	Omit the flag: jira issue link KEY1 KEY2 Blocks
Create command takes 5-10s	Normal Jira Cloud API latency	Expected behavior

Resources

• references/commands.md — Full CLI command reference with all flags and examples
• references/formatting.md — What formatting survives the CLI's markdown-to-ADF conversion (the critical reference for writing descriptions)