JIRA CLI

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

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

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 two authentication modes:

Bearer Token Authentication (Recommended) - Uses API token directly
Basic Authentication - Uses username + API token (legacy)

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

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

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

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

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>`, `--status <status>`, `--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`
`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

# 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

Name		Name	Last commit message	Last commit date
Latest commit History 41 Commits
.github		.github
.husky		.husky
bin		bin
docs		docs
examples		examples
lib		lib
scripts		scripts
tests		tests
.commitlintrc.js		.commitlintrc.js
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.releaserc.json		.releaserc.json
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
MIGRATION.md		MIGRATION.md
README.md		README.md
SECURITY.md		SECURITY.md
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

JIRA CLI

✨ Features

🚀 Quick Start

Installation

Setup

Configuration

Option 1: Command Line Configuration

Jira REST API Version

Option 2: Environment Variables

New format (JIRA_HOST)

Legacy format (JIRA_DOMAIN)

Getting Your API Token

Usage

Read an Issue

List Issues

Create a New Issue

Update an Existing Issue

Search Issues

Manage Comments

Project Management

Sprint Management

Commands

Configuration File

Examples

Development

Project Structure

Error Handling

Troubleshooting

Common Issues

Debug Mode

Contributing

Getting Started

Commit Message Format

Automated Releases

License

Roadmap

Support & Feedback

💬 We'd love to hear from you!

🐛 Found a bug?

💡 Have a feature idea?

📝 General feedback?

🤝 Want to contribute?

📈 Usage Analytics

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 12

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages