jira-ai-cli

AI-first Jira CLI built on the Jira REST API v3. Designed for AI agents and automation — structured output, Markdown-to-ADF conversion, image attachment handling, and batch operations.

Install

npm install -g jira-ai-cli

Setup

Set three environment variables:

export ATLASSIAN_BASE_URL="https://your-site.atlassian.net"
export ATLASSIAN_USER_EMAIL="[email protected]"
export ATLASSIAN_API_TOKEN="your-api-token"

Create an API token at https://id.atlassian.com/manage-profile/security/api-tokens

Verify with:

jira auth

Commands

Issues

jira view PROJ-123                         # View issue with description, comments, images
jira view PROJ-123 --json                  # JSON output for programmatic use
jira create --project PROJ --type Bug --summary "Login crash" --description @bug.md
jira edit PROJ-123 --summary "New title" --labels-add urgent --field priority=High
jira search 'project = PROJ AND status = "In Progress"' --max 20
jira transition PROJ-123 --status "In Review"
jira transition PROJ-123 --list            # Show available transitions
jira assign PROJ-123 --account-id 712020:xxx
jira assign PROJ-123 --unassign

Comments

jira comment PROJ-123 --body "Looks good, merging now"
jira comment PROJ-123 --body @review.md    # Read from file (Markdown → ADF)
jira comment PROJ-123 --edit 10042 --body "Updated comment"
jira comment PROJ-123 --delete 10042

Attachments

jira attach PROJ-123 screenshot.png log.txt
jira download PROJ-123 --images-only
jira delete-attachment 12345 67890

Sprint / Agile

jira sprint --project PROJ                 # Board → active sprint → issues
jira sprint --board 42 --state active,future
jira sprint --sprint 100 --json

Issue Links

jira link PROJ-1 PROJ-2 --type "blocks"
jira link --list-types

Users

jira user "John"                           # Search by name
jira user "[email protected]"               # Search by email
jira user --me                             # Current user (get your accountId)

Work Logs

jira worklog PROJ-123 --time "2h 30m" --comment "Backend refactoring"
jira worklog PROJ-123                      # List worklogs

Fields Discovery

jira fields PROJ-123                       # Editable fields for existing issue
jira fields --project PROJ --type Bug      # Creatable fields for new issue
jira fields PROJ-123 --filter priority     # Filter by name

Projects

jira project                               # List all accessible projects

Batch Operations

# Preview (dry-run by default)
jira batch --jql 'project = PROJ AND status = "To Do"' --labels-add needs-triage

# Execute
jira batch --jql 'project = PROJ AND status = "To Do"' --labels-add needs-triage --execute

# Batch transition
jira batch --jql 'labels = auto-close' --transition "Done" --resolution "Done" --execute

# Batch comment
jira batch --jql 'sprint in openSprints()' --comment "Sprint review done" --execute

Key Features

Markdown → ADF Conversion

All text inputs (description, comments, worklogs) automatically convert Markdown to Atlassian Document Format. Tables, code blocks, headings, lists — all render correctly in Jira.

jira create --project PROJ --type Task --summary "Deploy" --description @deploy-plan.md

AI-Friendly Output

• Structured text output: KEY | Type | Status | Priority | Assignee | Summary
• --json flag on every command for programmatic consumption
• Image attachments auto-downloaded to predictable paths (/tmp/jira-attachments/<key>/)
• Error messages include remediation instructions

Input Flexibility

Text arguments support three sources:

• Direct string: --body "Hello world"
• File: --body @notes.md
• Stdin: --body - (pipe from another command)

Custom Fields

# Discover field IDs first
jira fields PROJ-123 --filter "Testing Environment"

# Then set them
jira edit PROJ-123 --field 'customfield_10050={"value":"dev"}'
jira create --project PROJ --type Bug --summary "Fix" --field story_points=5

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | ATLASSIAN_BASE_URL | Yes | Jira Cloud URL (e.g. https://your-site.atlassian.net) | | ATLASSIAN_USER_EMAIL | Yes | Account email | | ATLASSIAN_API_TOKEN | Yes | API token from Atlassian account settings |

Requirements

• Node.js >= 18
• Jira Cloud instance with REST API v3
• Sprint commands require Jira Software (Agile API)

License

MIT