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

1. Configure using CLI options (Bearer auth - recommended):

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

2. Or with username for Basic authentication:

   jira config --server https://your-jira-instance.atlassian.net \
               --username [email protected] \
               --token your-api-token

3. 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 [email protected]
   export JIRA_API_VERSION=auto  # optional: auto (default), 2, 3

4. Verify connection:

   jira config --show
   jira issue view PROJ-123

5. Create a new issue:

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

6. View project information:

   jira project list

Configuration

JIRA CLI supports two authentication modes:

1. Bearer Token Authentication (Recommended) - Uses API token directly
2. 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 [email protected] \
            --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 [email protected]  # 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="[email protected]"
export JIRA_API_VERSION="auto"  # optional: auto (default), 2, 3

Legacy format (JIRA_DOMAIN)

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

Getting Your API Token

1. Go to Atlassian Account Settings
2. Click "Create API token"
3. Give it a label (e.g., "jira-cli")
4. 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 [email protected] \
            --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

1. "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)

2. "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

3. "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

4. "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

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes following our coding standards
4. Write tests for new functionality
5. 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"

6. Push to the branch (git push origin feature/amazing-feature)
7. 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

• [x] Basic issue management (create, read, update, delete)
• [x] Comment management (add, list, edit, delete)
• [x] Project and sprint management
• [x] Configuration management
• [x] Non-interactive, automation-friendly CLI
• [x] Analytics and reporting
• [x] Export issues to markdown format
• [x] Create/update issues from markdown files
• [ ] Issue templates
• [ ] Bulk operations
• [ ] Integration with other Atlassian tools
• [ ] Issue attachments management
• [ ] Workflows and transitions
• [ ] Custom fields support
• [ ] Time tracking

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?

1. Check the Issues page
2. Create a new bug report

💡 Have a feature idea?

1. Create a feature request
2. 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