README

A beautiful, interactive CLI wizard for creating Jira tickets with smart defaults and an intuitive user experience. Skip the web interface hassle and create tickets directly from your terminal!

✨ Features

🧙‍♂️ Interactive Wizard: Step-by-step guided ticket creation
🎯 Smart Defaults: Suggests active sprints, recent epics, and assignees
🚀 Quick Creation: Create tickets based on existing ones
🔄 Template System: Copy settings from existing tickets
🔒 Secure: API token-based authentication
🎨 Beautiful UI: Colorful, user-friendly terminal interface
⚡ Fast Setup: One-command configuration
📋 Complete Support: Projects, issue types, priorities, assignees, sprints, and epics
🔗 Epic Linking: Automatically link tickets to epics
🏃 Sprint Integration: Add tickets to active sprints
📊 Status Monitoring: Check configuration and connection status
🔍 Smart Search: Find projects, users, and issue types by name or partial match

🚀 Quick Start

Installation

composer require mi-lopez/jira-cli-wizard --dev

Configuration

Configure your Jira credentials (one-time setup):

./vendor/bin/jira-wizard configure

You'll need:

Your Jira instance URL (e.g., https://yourcompany.atlassian.net)
Your email address
An API token (generate here)

Create Your First Ticket

./vendor/bin/jira-wizard create

The wizard will guide you through:

Project Selection - Choose from your accessible projects
Issue Type - Select Story, Bug, Task, etc.
Summary - Enter a descriptive title
Description - Add details (optional)
Priority - Set importance level
Assignee - Assign to team members or leave unassigned
Additional Options - Link to epics, add to active sprint

🔥 Power Features

Create from Existing Ticket

The fastest way to create similar tickets:

# Copy all settings from an existing ticket
./vendor/bin/jira-wizard create-from CAM-1106

# Copy to a different project
./vendor/bin/jira-wizard create-from CAM-1106 --project TRIGB2B

What gets copied:

✅ Project (or override with --project)
✅ Issue type
✅ Priority
✅ Assignee
✅ Epic (if linked)
✅ Sprint (current active sprint)

What you provide:

✅ New summary
✅ New description
✅ Optional: modify any copied settings

📖 Usage Examples

Standard Ticket Creation

$ ./vendor/bin/jira-wizard create

🎯 Jira CLI Wizard
==================

✅ Connected to Jira successfully!

[1/7] Select Project
--------------------
Available projects:
  [0] PROJ - My Project
  [1] DEV - Development Team
  [2] CAM - CAMEL NETWORKS - OroCommerce project
> 2

[2/7] Select Issue Type
-----------------------
Available issue types:
  [0] Tarea - Un trabajo pequeño e independiente
  [1] Historia - Una función o funcionalidad expresada como objetivo del usuario
  [2] Error - Un problema o error
> 1

[3/7] Enter Summary
-------------------
Enter ticket summary: Implement user authentication system

[4/7] Enter Description
-----------------------
Enter description (optional): Add JWT-based authentication with login/logout functionality

[5/7] Select Priority
---------------------
Available priorities:
  [skip] Skip (use default)
  [0] Highest
  [1] High
  [2] Medium
> 1

[6/7] Select Assignee
--------------------
Available assignees:
  [unassigned] Unassigned
  [0] John Doe
  [1] Jane Smith
  [2] Miguel Lopez
> 2

[7/7] Additional Options
-----------------------
🏃 Sprint Options
Add to active sprint 'Sprint 23'? (y/N): y
✅ Will add to sprint: Sprint 23

📚 Epic Options
Select epic (optional):
  [skip] Skip (no epic)
  [0] CAM-1037 - Oro 6.1 Upgrade
  [1] CAM-761 - MVP3 Distributor Quote
> 0

📋 Ticket Summary
================
📁 Project: CAM - CAMEL NETWORKS - OroCommerce project
🎯 Type: Historia
📝 Summary: Implement user authentication system
📄 Description: Add JWT-based authentication with login/logout functionality
⚡ Priority: High
👤 Assignee: Miguel Lopez
🏃 Sprint: Sprint 23
📚 Epic: CAM-1037

🤔 Create this ticket? (y/N): y

🚀 Creating ticket...
✅ Ticket created successfully!
📝 Issue Key: CAM-1107
🔗 URL: https://yourcompany.atlassian.net/browse/CAM-1107
📋 Adding to sprint...
✅ Added to sprint!

Quick Template Creation

$ ./vendor/bin/jira-wizard create-from CAM-1106

📋 Original Ticket Template
============================
📁 Project: CAM - CAMEL NETWORKS - OroCommerce project
🎯 Type: Tarea
📝 Summary: Test from API
⚡ Priority: Medium
👤 Assignee: Miguel Lopez
🏃 Sprint: CAMEL Sprint 18
📚 Epic: CAM-1037 - Oro 6.1 Upgrade

🎯 Create New Ticket
====================
📁 Project: CAM - CAMEL NETWORKS - OroCommerce project

📝 Enter new ticket summary: Fix login validation bug
📄 Enter description (optional): Users cannot login with special characters in password
🔧 Do you want to modify the copied settings? (y/N): n

📋 New Ticket Summary
=====================
📁 Project: CAM - CAMEL NETWORKS - OroCommerce project
🎯 Type: Tarea
📝 Summary: Fix login validation bug
📄 Description: Users cannot login with special characters in password
⚡ Priority: Medium
👤 Assignee: Miguel Lopez
🏃 Sprint: CAMEL Sprint 18
📚 Epic: CAM-1037

🤔 Create this ticket? (y/N): y

🚀 Creating ticket...
✅ Ticket created successfully!
📝 Issue Key: CAM-1108
🔗 URL: https://yourcompany.atlassian.net/browse/CAM-1108
📋 Adding to sprint...
✅ Added to sprint!

Cross-Project Template

$ ./vendor/bin/jira-wizard create-from CAM-1106 --project TRIGB2B

📋 Original Ticket Template
============================
📁 Project: CAM - CAMEL NETWORKS - OroCommerce project
🎯 Type: Tarea
📝 Summary: Test from API
⚡ Priority: Medium
👤 Assignee: Miguel Lopez

🎯 Create New Ticket
====================
📁 Project: TRIGB2B - TRIGANO - B2B - Projet OroCommerce

📝 Enter new ticket summary: Implement similar API feature
📄 Enter description (optional): Port the API functionality to TRIGB2B project
🔧 Do you want to modify the copied settings? (y/N): y

⚡ Change priority? (y/N): y
Available priorities:
  [skip] Skip (use default)
  [0] Highest
  [1] High
  [2] Medium
> 1

👤 Change assignee? (y/N): n

🚀 Creating ticket...
✅ Ticket created successfully!
📝 Issue Key: TRIGB2B-456

🛠️ Available Commands

Create Ticket (Interactive)

./vendor/bin/jira-wizard create
# or simply:
./vendor/bin/jira-wizard

Full interactive wizard for creating tickets from scratch.

Create from Template

./vendor/bin/jira-wizard create-from <ISSUE-KEY>

Create a new ticket using an existing ticket as a template.

Examples:

# Copy all settings from CAM-1106
./vendor/bin/jira-wizard create-from CAM-1106

# Copy settings but create in different project
./vendor/bin/jira-wizard create-from CAM-1106 --project TRIGB2B

# Quick bug fix based on existing bug
./vendor/bin/jira-wizard create-from PROJ-123

Configure Credentials

./vendor/bin/jira-wizard configure

Set up or update your Jira credentials and connection settings.

Check Status

./vendor/bin/jira-wizard status

Display current configuration and test connection to Jira.

Get Help

./vendor/bin/jira-wizard --help
./vendor/bin/jira-wizard create-from --help

⚙️ Configuration

Configuration is stored in ~/.jira-cli-config.json. You can:

View current config: ./vendor/bin/jira-wizard status
Reconfigure: ./vendor/bin/jira-wizard configure
Manual edit: Edit ~/.jira-cli-config.json directly

Environment Variables

You can also set configuration via environment variables:

export JIRA_URL="https://yourcompany.atlassian.net"
export JIRA_EMAIL="your.email@company.com"
export JIRA_TOKEN="your-api-token"

🎯 Smart Features

Flexible Selection

All selection prompts support multiple input methods:

Projects:

Number: 10 (from numbered list)
Project key: CAM (exact match)
Partial key: CAM (if unique)
Project name: CAMEL (partial match)

Issue Types:

Number: 0 (from numbered list)
Type name: Tarea or Historia
Partial name: Hist (matches Historia)

Priorities:

Number: 2 (from numbered list)
Priority name: High or Medium
Skip: skip (use default)

Assignees:

Number: 15 (from numbered list)
Full name: Miguel Lopez
Email: miguel@company.com
Partial name: Miguel
Unassigned: unassigned

Smart Defaults

Active Sprint: Automatically suggests current active sprint
Recent Epics: Shows epics ordered by last updated
Team Members: Lists assignable users for the project
Cross-Project: Maintains settings when copying between projects

Error Handling

Connection Testing: Validates credentials before use
Graceful Fallbacks: Continues even if optional features fail
Clear Messages: Descriptive error messages with solutions
Multiple Matches: Shows options when partial matches are ambiguous

🔧 Requirements

PHP: ^8.1
Jira: Cloud or Server with REST API access
Extensions: curl, json

🎨 Advanced Usage

Workflow Integration

Create tickets as part of your development workflow:

# Create a bug report for current issue
./vendor/bin/jira-wizard create-from PROJ-123

# Create feature ticket based on existing epic structure
./vendor/bin/jira-wizard create-from EPIC-456 --project NEWPROJ

# Quick task creation for sprint
./vendor/bin/jira-wizard create-from SPRINT-TEMPLATE

Batch Operations

Use shell scripting for batch operations:

#!/bin/bash
# Create multiple related tickets
for feature in "login" "signup" "profile"; do
    echo "Creating ticket for $feature"
    ./vendor/bin/jira-wizard create-from TEMPLATE-123 \
        --project MYPROJ \
        --summary "Implement $feature feature"
done

Team Productivity

Project Templates:

Create a "template" ticket for each project type
Use create-from to maintain consistency
Share template ticket keys with team

Sprint Planning:

Clone user stories with create-from
Maintain epic linkage across related tickets
Quickly create test tickets for each feature

Custom Fields Support

The wizard automatically handles:

Standard Fields: Summary, Description, Priority, Assignee
Project Fields: Issue Types, Components, Versions
Agile Fields: Sprint, Epic, Story Points
Custom Fields: (via template copying)

🐛 Troubleshooting

Common Issues

Connection Failed

❌ Connection failed: Unauthorized

Solution: Check your email and API token. Regenerate token if needed.

No Projects Found

No projects found or no access to projects.

Solution: Ensure your account has access to at least one Jira project.

Permission Denied

Failed to create issue: Forbidden

Solution: Verify you have permission to create issues in the selected project.

Template Ticket Not Found

❌ Ticket CAM-1106 not found or no access.

Solution: Check the ticket key and ensure you have access to view it.

Invalid Project Override

Project INVALID not found or no access.

Solution: Verify the project key exists and you have access to it.

Debug Information

# Check current status and configuration
./vendor/bin/jira-wizard status

# View detailed configuration
cat ~/.jira-cli-config.json

# Test connection manually
curl -u "email@example.com:api-token" \
  "https://yourcompany.atlassian.net/rest/api/3/myself"

# Test specific ticket access
curl -u "email@example.com:api-token" \
  "https://yourcompany.atlassian.net/rest/api/3/issue/CAM-1106"

Performance Tips

Connection Caching: The CLI tests connection once per session
Project Caching: Project lists are cached during wizard execution
API Optimization: Minimal API calls for better performance
Batch Operations: Use templates for creating multiple similar tickets

Getting Help

🧪 Development

Setup Development Environment

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

# Install dependencies
composer install

# Run tests
composer test

# Check code style
composer cs-check

# Fix code style
composer cs-fix

# Run static analysis
composer phpstan

Project Structure

├── bin/
│   └── jira-wizard                  # CLI entry point
├── src/
│   ├── Commands/
│   │   ├── CreateTicketCommand.php  # Main wizard command
│   │   ├── CreateFromCommand.php    # Template creation command
│   │   ├── ConfigureCommand.php     # Configuration command
│   │   └── StatusCommand.php        # Status command
│   ├── Helpers/
│   │   └── ConsoleHelper.php        # Pretty console output
│   ├── JiraApiClient.php            # Jira API integration
│   ├── ConfigManager.php            # Configuration management
│   └── Installer.php               # Post-install setup
├── tests/                           # PHPUnit tests
├── .github/
│   └── workflows/                   # GitHub Actions CI
├── composer.json                    # Package configuration
└── README.md                        # This file

Running Tests

# Run all tests
composer test

# Run tests with coverage
composer test-coverage

# Run specific test
./vendor/bin/phpunit tests/Unit/ConfigManagerTest.php

🤝 Contributing

We welcome contributions! Please follow these steps:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Add tests for new functionality
Ensure all tests pass (composer test)
Check code style (composer cs-check)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Code Style

This project follows PSR-12 coding standards:

# Check code style
composer cs-check

# Auto-fix code style issues
composer cs-fix

🔒 Security

API Token Security

API tokens are stored locally in ~/.jira-cli-config.json
Tokens are never logged or transmitted except to Jira
Use file permissions to protect your config: chmod 600 ~/.jira-cli-config.json

Best Practices

Generate dedicated tokens: Create a token specifically for CLI use
Regular rotation: Rotate API tokens periodically
Minimal permissions: Use accounts with minimal required permissions
Secure storage: Keep your config file secure

📋 Roadmap

Version 1.1.0

Bulk Operations: Create multiple tickets at once
Custom Templates: Save and reuse ticket templates locally
Custom Fields: Enhanced support for custom Jira fields
Watchers: Add watchers to tickets during creation
Project Shortcuts: Quick project selection via aliases

Version 1.2.0

Comments: Add initial comments to tickets
Attachments: Upload files to tickets
Sub-tasks: Create sub-tasks automatically
Time Tracking: Add time estimates and logging
Workflows: Support for custom workflow transitions

Version 2.0.0

Multiple Instances: Support multiple Jira instances
Plugins: Plugin system for extensions
GUI Mode: Optional web interface
AI Integration: AI-powered descriptions and summaries
Git Integration: Create tickets from git commits/branches

📊 Performance

Cold start: ~200ms (first run after configuration)
Warm start: ~100ms (subsequent runs)
Template operations: ~150ms (including API calls)
API calls: Optimized to minimize requests
Memory usage: ~12MB typical usage

🌟 Star History

If this tool saves you time, please consider giving it a star! ⭐

📄 License

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

🙏 Acknowledgments

Atlassian: For providing the excellent Jira REST API
Symfony Console: For the powerful CLI framework
Guzzle HTTP: For reliable HTTP client functionality
Contributors: All the amazing people who help improve this tool

📈 Changelog

[1.0.0] - 2025-07-03

🎉 Initial release
✨ Interactive ticket creation wizard
🔧 One-command configuration setup
🎯 Smart defaults for sprints and epics
🎨 Beautiful terminal interface
📊 Status and health checking
🔒 Secure API token authentication
🚀 NEW: Create from existing ticket templates
🔄 NEW: Cross-project ticket copying
🔍 NEW: Smart search and selection
⚡ NEW: Quick ticket creation workflows

Made with ❤️ and PHP by mi-lopez

⬆ Back to top

mi-lopez / jira-cli-wizard

Maintainers

Details