A modern, extensible command-line interface for Atlassian JIRA built with Factory pattern and Commander.js. Manage your issues, projects, and sprints directly from the terminal with a beautiful, user-friendly interface.

✨ Features

📋 Issue Management: Create, read, update, and delete JIRA issues with full CRUD operations
💬 Comment Management: Add, list, edit, and delete comments on issues with file support
📝 Markdown Support: Export issues to markdown files and create/update issues from markdown
📊 Project Information: View project details, statistics, and team insights
🏃 Sprint Management: Monitor sprint progress, burndown charts, and team velocity
⚙️ Smart Configuration: Environment variables and CLI options for flexible setup
📈 Advanced Analytics: Get insights into project health, user workload, and performance metrics
🤖 Automation-Friendly: Fully scriptable, non-interactive mode for CI/CD pipelines
🎨 Beautiful Output: Formatted tables, colored output, and progress indicators
🔍 Powerful Search: Filter issues with JQL-like queries and advanced search options
🏗️ Modern Architecture: Factory pattern, dependency injection, and extensible command structure
🛡️ Secure: Support for API tokens, environment variables, and secure credential storage

🚀 Quick Start

Installation

# Install globally via npm
npm install -g @pchuri/jira-cli

# Or use npx (no installation required)
npx @pchuri/jira-cli

# Or install locally for development
git clone https://github.com/pchuri/jira-cli.git
cd jira-cli
npm install
npm link

Claude Code Skill

Install the packaged Jira skill into the current project:

jira install-skill

This copies the skill to ./.claude/skills/jira/SKILL.md.

If the file already exists, the command errors by default. Use --force to overwrite:

jira install-skill --force

Use a custom destination directory if needed:

jira install-skill --dest ./custom/skills/jira

Setup

Configure using CLI options (Bearer auth - recommended):

jira config --server https://your-jira-instance.atlassian.net \
            --token your-api-token

Or with username for Basic authentication:

jira config --server https://your-jira-instance.atlassian.net \
            --username your-email@company.com \
            --token your-api-token

Or use environment variables:

# Bearer authentication (recommended)
export JIRA_HOST=your-jira-instance.atlassian.net
export JIRA_API_TOKEN=your-api-token
export JIRA_API_VERSION=auto  # optional: auto (default), 2, 3

# Basic authentication (optional)
export JIRA_HOST=your-jira-instance.atlassian.net
export JIRA_API_TOKEN=your-api-token
export JIRA_USERNAME=your-email@company.com
export JIRA_API_VERSION=auto  # optional: auto (default), 2, 3

# Scoped API token (Atlassian Cloud) — also set Cloud ID
export JIRA_CLOUD_ID=your-cloud-id  # routes through Atlassian Platform API Gateway

Verify connection:

jira config --show
jira issue view PROJ-123

Create a new issue:

jira issue create --project PROJ --type Bug --summary "Login fails"

View project information:
```
jira project list
```

Configuration

JIRA CLI supports the following authentication modes:

Bearer Token Authentication (Recommended) - Uses API token directly
Basic Authentication - Uses username + API token (legacy)
Scoped API Token (Atlassian Cloud) - Basic auth + Cloud ID, routed through the Atlassian Platform API Gateway. Use this for Atlassian's newer scoped API tokens.

Option 1: Command Line Configuration

# Bearer authentication (server + token only)
jira config --server https://yourcompany.atlassian.net \
            --token your-api-token

# Basic authentication (with username)
jira config --server https://yourcompany.atlassian.net \
            --username your-email@company.com \
            --token your-api-token

# Scoped API token (Atlassian Cloud) — set Cloud ID to route via the Platform API Gateway
jira config --server https://yourcompany.atlassian.net \
            --username your-email@company.com \
            --token your-scoped-api-token \
            --cloud-id your-cloud-id

# Or set individual values
jira config set server https://yourcompany.atlassian.net
jira config set token your-api-token
jira config set username your-email@company.com  # optional
jira config set cloudId your-cloud-id            # optional, enables scoped tokens
jira config set apiVersion auto  # optional: auto (default), 2, 3

# Show current configuration
jira config --show

Jira REST API Version

By default, the CLI uses auto mode: it tries Jira REST API v3 first and automatically retries with v2 if needed. If a fallback happens, the CLI keeps using the working version for the rest of the process.

You can override the behavior:

Config: jira config set apiVersion auto|2|3
Env: JIRA_API_VERSION=auto|2|3

Option 2: Environment Variables

You can configure the CLI using environment variables in either a new or legacy format:

New format (JIRA_HOST)

# Bearer authentication
export JIRA_HOST="your-jira-instance.atlassian.net"
export JIRA_API_TOKEN="your-api-token"
export JIRA_API_VERSION="auto"  # optional: auto (default), 2, 3

# Basic authentication (add username)
export JIRA_HOST="your-jira-instance.atlassian.net"
export JIRA_API_TOKEN="your-api-token"
export JIRA_USERNAME="your-email@company.com"
export JIRA_API_VERSION="auto"  # optional: auto (default), 2, 3

Legacy format (JIRA_DOMAIN)

export JIRA_DOMAIN="your-domain.atlassian.net"
export JIRA_USERNAME="your-email@company.com"
export JIRA_API_TOKEN="your-api-token"
export JIRA_API_VERSION="auto"  # optional: auto (default), 2, 3

Scoped API Tokens (Atlassian Cloud)

Atlassian recommends using scoped API tokens over classic (unscoped) tokens. Scoped tokens require requests to go through the Atlassian Platform API Gateway at https://api.atlassian.com/ex/jira/{cloudId} instead of https://{your-site}.atlassian.net.

To use a scoped token, configure your Cloud ID in addition to the usual server, username, and token:

# Via flags
jira config --server https://yourcompany.atlassian.net \
            --username your-email@company.com \
            --token your-scoped-api-token \
            --cloud-id your-cloud-id

# Or via env vars (works with both JIRA_HOST and JIRA_DOMAIN formats)
export JIRA_CLOUD_ID="your-cloud-id"

When cloudId is set, all REST API and Agile API requests are automatically routed through the Platform API Gateway. Without it, requests use the configured server URL directly (compatible with classic tokens, Jira Data Center, and Jira Server).

Finding Your Cloud ID

You can fetch your Cloud ID without authentication by visiting (or curl-ing):

https://your-site.atlassian.net/_edge/tenant_info

The response contains a cloudId field. Copy it into --cloud-id or JIRA_CLOUD_ID.

mTLS Authentication (Client Certificate)

For self-hosted or reverse-proxied JIRA deployments that authenticate at the TLS layer with client certificates:

Command Line Configuration

jira config --server https://jira.example.com \
            --auth-type mtls \
            --tls-client-cert ~/.certs/client.pem \
            --tls-client-key ~/.certs/client.key \
            --tls-ca-cert ~/.certs/ca-chain.pem

Environment Variables

export JIRA_HOST="jira.example.com"
export JIRA_AUTH_TYPE="mtls"
export JIRA_TLS_CLIENT_CERT="~/.certs/client.pem"
export JIRA_TLS_CLIENT_KEY="~/.certs/client.key"
export JIRA_TLS_CA_CERT="~/.certs/ca-chain.pem"  # optional

Notes:

mTLS mode does not send an Authorization header; authentication happens at the TLS layer
The CA certificate is optional if your client certificate is signed by a well-known CA
mTLS is commonly used in enterprise environments with private certificate authorities
Paths beginning with ~/ are expanded to your home directory; certificate files are read at startup, so update the cert paths if they change

Getting Your API Token

Go to Atlassian Account Settings
Click "Create API token"
Give it a label (e.g., "jira-cli")
Copy the generated token

For scoped tokens, you can choose specific Jira scopes (e.g., read:jira-work, write:jira-work) when creating the token. Scoped tokens require Cloud ID configuration — see Scoped API Tokens (Atlassian Cloud).

Usage

Read an Issue

# View in terminal
jira issue view PROJ-123

# View as markdown in terminal
jira issue view PROJ-123 --format markdown

# Export to markdown file
jira issue view PROJ-123 --output ./issue.md

# Export with explicit markdown format
jira issue view PROJ-123 --format markdown --output ./issue.md

List Issues

# List all recent issues
jira issue --list

# Filter by project
jira issue --list --project PROJ

# Filter by assignee
jira issue --list --assignee john.doe

# Filter by status
jira issue --list --status "In Progress"

# Combine filters
jira issue --list --project PROJ --assignee john.doe --status "To Do"

Create a New Issue

# Create with required flags
jira issue create --project PROJ --type Bug --summary "Bug in login"

# With description
jira issue create --project PROJ --type Bug --summary "Bug in login" --description "User cannot login"

# With description from file
jira issue create --project PROJ --type Story --summary "Add feature" --description-file ./feature-spec.md

# With all options
jira issue create --project PROJ --type Bug --summary "Critical bug" \
                  --description "Details here" \
                  --assignee john.doe --priority High

Update an Existing Issue

# Update summary
jira issue edit PROJ-123 --summary "Updated summary"

# Update specific fields
jira issue edit PROJ-123 --assignee john.doe --priority High

# Update description
jira issue edit PROJ-123 --description "Updated description"

# Update description from file
jira issue edit PROJ-123 --description-file ./updated-spec.md

Search Issues

# Search issues with JQL filtering
jira issue list --jql "login bug"

jira issue list --jql "project = PROJ AND status = 'In Progress'"

# Limit results
jira issue list --jql "bug" --limit 5

Manage Comments

# Add a comment to an issue
jira issue comment add PROJ-123 "Review completed"

# Add multi-line comment
jira issue comment add PROJ-123 "Build status:
- Unit tests: ✓
- Integration tests: ✓
- Deployment: pending"

# Add comment from file
jira issue comment add PROJ-123 --file ./review-notes.md

# Add internal comment (visible only to team)
jira issue comment add PROJ-123 "Internal note" --internal

# List all comments on an issue
jira issue comment list PROJ-123

# List comments in JSON format
jira issue comment list PROJ-123 --format json

# Edit an existing comment
jira issue comment edit 12345 "Updated comment text"

# Edit comment from file
jira issue comment edit 12345 --file ./updated-notes.md

# Delete a comment (requires confirmation)
jira issue comment delete 12345 --force

# Using command alias
jira issue c add PROJ-123 "Quick comment"
jira issue c list PROJ-123

Manage Remote Links

Attach external resources (GitHub PRs, CI runs, dashboards, docs) to a Jira issue as Remote Links.

# List remote links on an issue
jira issue remote-link list PROJ-123

# List in JSON format
jira issue remote-link list PROJ-123 --format json

# Filter by globalId (useful to check if a link already exists)
jira issue remote-link list PROJ-123 --global-id https://github.com/org/repo/pull/42

# Add a remote link
jira issue remote-link add PROJ-123 \
    --url https://github.com/org/repo/pull/42 \
    --title "org/repo#42"

# Add with globalId for upsert behavior (Jira updates existing link with same globalId)
jira issue remote-link add PROJ-123 \
    --url https://github.com/org/repo/pull/42 \
    --title "org/repo#42" \
    --global-id https://github.com/org/repo/pull/42 \
    --relationship "relates to"

# Update an existing remote link
jira issue remote-link update PROJ-123 12345 --title "Updated title"

# Delete a remote link (requires --force)
jira issue remote-link delete PROJ-123 12345 --force

# Using command alias
jira issue rl list PROJ-123
jira issue rl add PROJ-123 --url https://example.com --title "Example"

Project Management

# List all projects
jira project list

# View project details
jira project view PROJ

Sprint Management

# List available boards first
jira sprint boards

# List sprints for specific board (required when multiple boards exist)
jira sprint list --board 123

# Show only active sprints
jira sprint active --board 123

# Filter by state
jira sprint list --board 123 --state active

Commands

Command	Description	Options
`config --server <url> --token <token>`	Configure CLI (Bearer auth)	Username optional; use `--username <email>` for Basic auth
`config --show`	Show current configuration	-
`config set <key> <value>`	Set individual config value	-
`issue view <key>`	View issue details (alias: show)	`--format <terminal\|markdown>`, `--output <path>`
`issue list`	List issues	`--project <key>`, `--assignee <user>`, `--reporter <user>`, `--status <status>`, `--type <type>`, `--priority <level>`, `--created <date>`, `--updated <date>`, `--jql <query>`, `--limit <number>`
`issue create`	Create new issue	Required: `--project <key>`, `--type <type>`, `--summary <text>` Optional: `--description <text>`, `--description-file <path>`, `--assignee <user>`, `--priority <level>`
`issue edit <key>`	Edit an existing issue (alias: update)	At least one required: `--summary <text>`, `--description <text>`, `--description-file <path>`, `--assignee <user>`, `--priority <level>`
`issue delete <key>`	Delete issue	Required: `--force`
`issue comment add <key> [text]`	Add comment to issue (alias: c)	`[text]` or `--file <path>` Optional: `--internal`
`issue comment list <key>`	List comments on issue	`--format <table\|json>` (default: table)
`issue comment edit <id> [text]`	Edit existing comment	`[text]` or `--file <path>`
`issue comment delete <id>`	Delete comment	Required: `--force`
`issue remote-link list <key>`	List remote links on issue (alias: rl)	`--format <table\|json>` (default: table), `--global-id <id>`
`issue remote-link add <key>`	Add remote link to issue	Required: `--url <url>`, `--title <title>` Optional: `--global-id <id>`, `--relationship <rel>`, `--summary <text>`, `--icon-url <url>`, `--icon-title <title>`
`issue remote-link update <key> <linkId>`	Update an existing remote link	At least one required: `--url <url>`, `--title <title>`, `--relationship <rel>`, `--summary <text>`, `--icon-url <url>`, `--icon-title <title>`
`issue remote-link delete <key> <linkId>`	Delete remote link	Required: `--force`
`project list`	List all projects	`--type <type>`, `--category <category>`
`project view <key>`	View project details	-
`project components <key>`	List project components	-
`project versions <key>`	List project versions	-
`sprint list`	List sprints	`--board <id>` (required when multiple boards), `--state <state>`, `--active`
`sprint active`	List active sprints	`--board <id>` (required when multiple boards)
`sprint boards`	List available boards	-

Configuration File

Configuration is stored using the conf package in your system's config directory:

macOS: ~/Library/Preferences/jira-cli/config.json
Linux: ~/.config/jira-cli/config.json
Windows: %APPDATA%\jira-cli\config.json

Examples

# Setup (Bearer auth - recommended)
jira config --server https://jira.company.com \
            --token your-api-token

# Setup (Basic auth with username)
jira config --server https://jira.company.com \
            --username user@company.com \
            --token your-api-token

# View an issue in terminal
jira issue view PROJ-123

# View as markdown in terminal
jira issue view PROJ-123 --format markdown

# Export to markdown file
jira issue view PROJ-123 --output ./issue.md

# List issues with filters
jira issue list --project PROJ --status "In Progress" --limit 10

# Create new issue
jira issue create --project PROJ --type Bug --summary "Login fails"

# Create issue with description file
jira issue create --project PROJ --type Story \
                  --summary "Add feature" \
                  --description-file ./feature-spec.md

# Update issue
jira issue edit PROJ-123 --summary "Updated summary"

# Delete issue (requires --force)
jira issue delete PROJ-123 --force

# Add comment to an issue
jira issue comment add PROJ-123 "Review completed"

# Add comment from file
jira issue comment add PROJ-123 --file ./review-notes.md

# List all comments
jira issue comment list PROJ-123

# Edit a comment
jira issue comment edit 12345 "Updated comment"

# Delete a comment
jira issue comment delete 12345 --force

# Add a GitHub PR as a remote link
jira issue remote-link add PROJ-123 \
    --url https://github.com/org/repo/pull/42 \
    --title "org/repo#42" \
    --global-id https://github.com/org/repo/pull/42 \
    --relationship "relates to"

# List remote links
jira issue remote-link list PROJ-123

# Delete a remote link
jira issue remote-link delete PROJ-123 12345 --force

# List all projects
jira project list

# Show available boards
jira sprint boards

# Show active sprints
jira sprint active --board 123

Development

# Clone the repository
git clone https://github.com/pchuri/jira-cli.git
cd jira-cli

# Install dependencies
npm install

# Run locally
npm start -- --help

# Run tests
npm test

# Lint code
npm run lint

Project Structure

jira-cli/
├── bin/
│   ├── index.js              # Main CLI entry point
│   └── commands/             # Command implementations
│       ├── config.js         # Configuration management
│       ├── issue.js          # Issue operations
│       ├── project.js        # Project operations
│       └── sprint.js         # Sprint operations
├── lib/
│   ├── jira-client.js        # JIRA API client
│   ├── config.js             # Configuration management
│   ├── utils.js              # Utility functions
│   └── analytics.js          # Analytics and reporting
├── tests/
│   └── jira-client.test.js   # Unit tests
├── docs/                     # Documentation
├── examples/                 # Usage examples
└── package.json

Error Handling

The CLI provides clear error messages for common issues:

Authentication failures: Check your credentials with jira config --show
Network errors: Verify your server URL and connection
Permission errors: Ensure your account has the necessary permissions
Invalid issue keys: Double-check the issue key format (PROJ-123)

Troubleshooting

Common Issues

"JIRA CLI is not configured"
- Run jira config --server <url> --token <token> to set up your connection
- Optionally add --username <email> for Basic authentication
- Or set environment variables (JIRA_HOST + JIRA_API_TOKEN required, JIRA_USERNAME optional)
"Authentication failed"
- Verify your username and API token with jira config --show
- Make sure you're using an API token, not your password
- Check if your token has expired
"Network error"
- Check your server URL format: https://yourcompany.atlassian.net
- Ensure you can access JIRA from your network
- Try with curl to test connectivity
"Resource not found"
- Verify the issue key or project key exists
- Check if you have permission to access the resource
- Use jira search to find the correct issue key

Debug Mode

Set the DEBUG environment variable to get more detailed output:

DEBUG=jira-cli* jira issue --list

Or disable analytics:

export JIRA_CLI_ANALYTICS=false

Contributing

We use Conventional Commits and Semantic Release for automated versioning and changelog generation.

Getting Started

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes following our coding standards
Write tests for new functionality

Commit your changes using conventional commit format:

# Examples:
git commit -m "feat: add issue filtering by labels"
git commit -m "fix: resolve authentication timeout issue"  
git commit -m "docs: update installation instructions"

Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Commit Message Format

We follow the Conventional Commits specification:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types: feat, fix, docs, style, refactor, perf, test, chore, ci

Examples:

feat(auth): add OAuth2 support
fix(cli): handle empty project names correctly
docs: update README with new examples
test: add unit tests for issue creation

Automated Releases

Push to main: Triggers automated release based on commit types
Breaking changes: Use feat!: or BREAKING CHANGE: in footer
Versioning: Automatically determined by semantic-release
Changelog: Generated from conventional commits
NPM publish: Automated via GitHub Actions

Read our full Contributing Guide for detailed guidelines.

License

This project is licensed under the ISC License - see the LICENSE file for details.

Roadmap

Support & Feedback

💬 We'd love to hear from you!

Your feedback helps make jira-cli better for everyone. Here's how you can share your thoughts:

🐛 Found a bug?

Check the Issues page
Create a new bug report

💡 Have a feature idea?

Create a feature request
Join our Discussions to chat with the community

📝 General feedback?

Share your experience with a feedback issue
Rate us on NPM
Star the repo if you find it useful! ⭐

🤝 Want to contribute?

Check out our Contributing Guide - all contributions are welcome!

📈 Usage Analytics

To help us understand how jira-cli is being used and improve it, we collect anonymous usage statistics. This includes:

Command usage frequency (no personal data)
Error patterns (to fix bugs faster)
Feature adoption metrics

You can opt-out anytime by setting: export JIRA_CLI_ANALYTICS=false

Made with ❤️ for the JIRA community

Keywords

FAQs

What is @pchuri/jira-cli?

Is @pchuri/jira-cli well maintained?

Package last updated on 18 Jun 2026

@pchuri/jira-cli

JIRA CLI