Jira CLI

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

Critical Rules

• Always use --no-input to suppress interactive prompts (except issue link which does not support it)

• Never use -b for long descriptions — it causes the CLI to hang. Use file + pipe instead

• --template flag only works on create and comment add , not on edit

• The CLI uses a markdown-to-ADF parser — see references/formatting.md for what works and what breaks

• Pipe from stdin for descriptions longer than 2-3 lines

• 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

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