Download the PHP package mi-lopez/jira-cli-wizard without Composer

🎯 Jira CLI Wizard

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
• 🤖 Non-Interactive Mode: Create tickets from scripts and AI agents using flags
• 🎯 Smart Defaults: Suggests active sprints, recent epics, and assignees
• 🚀 Quick Creation: Create tickets based on existing ones
• ✏️ Update Command: Modify fields on existing tickets, interactively or by flag
• 🔀 Workflow Transitions: Move a ticket's status by name, and list the moves that are legal right now
• 👀 View Command: Read a ticket and its comments in the terminal, with the text back in Markdown
• 📎 Attachments: Upload files and screenshots on create, create-from and update
• 📝 Markdown Descriptions: Headings, lists, bold, italic, code and links render as real Jira ADF
• 🏷️ Labels: Prompted in the wizard, prefilled from the template when copying a ticket
• 🔄 Template System: Copy settings from existing tickets
• 🔍 Resource Discovery: List projects, issue types, priorities, epics, sprints and transitions as JSON
• 🧪 Dry Run: Preview the full payload before creating any ticket
• 🔒 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

Configuration

Configure your Jira credentials (one-time setup):

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

The wizard will guide you through:

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

🔥 Power Features

Create from Existing Ticket

The fastest way to create similar tickets:

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

Quick Template Creation

Cross-Project Template

🛠️ Available Commands

Create Ticket (Interactive)

Full interactive wizard for creating tickets from scratch.

Create Ticket (Non-Interactive)

Skip the wizard entirely by passing flags. Outputs only the issue key to stdout — ideal for scripts and AI agents.

Available flags:

--assignee resolves by exact display name or email first, then by partial match. An ambiguous partial match is rejected with the list of candidates rather than silently picking one.

--dry-run requires --project, --type and --summary. Without them it fails instead of falling through to the interactive wizard, which would create a real ticket.

Capture the key in a script:

Preview before creating (dry-run):

Update an Existing Ticket

Fields accept the same values as create. Two update-specific conventions:

• --status moves the ticket through the workflow. Status is not a writable field in Jira, so this rides POST /issue/{key}/transitions instead of the field update. It accepts a transition id, a transition name, or the name of the resulting status, matched case-insensitively; an unambiguous fragment works too. When nothing matches, the error lists what is legal from the current status. Asking for the status the ticket already has is a no-op, not a failure, so re-running a script is safe.
• --assignee=unassigned (or none) clears the assignee.
• --epic=none clears the parent link.
• An empty --labels= clears every label, whereas omitting the flag leaves them untouched.

View a Ticket

The description comes back from Jira as ADF and is rendered in the same Markdown flavour create and update accept, so a ticket can be read, edited and sent back without the formatting drifting. Headings, lists, task lists, tables, code blocks, quotes, mentions and links are all preserved; attachments show as [attachment: name].

--comments (-c) appends the thread, oldest first, with author, date and an (edited …) marker when the comment was actually changed. Comments live behind their own endpoint, so they cost an extra request and are only fetched when you ask for them:

--json prints a flattened object — key, url, summary, status, type, priority, assignee, reporter, project, parent, labels, timestamps and the Markdown description — rather than Jira's raw payload, which also carries the changelog and every rendered field. With --comments it also carries a comments array (author, created, updated, Markdown body); without the flag the key is absent, which is a different claim from an empty list.

Attach Files

Works on create, create-from and update. The flag is repeatable and the wizard also prompts for files:

Missing files are reported before anything is sent to Jira.

Markdown in Descriptions

Descriptions are converted to Jira's ADF, so markdown renders as real formatting instead of literal characters:

Supported: headings, bullet and ordered lists, **bold**, *italic*, `code`, [links](url), blank lines as paragraph breaks and single newlines as hard breaks.

List Resources as JSON

Discover valid values for flags before scripting or using with an AI agent:

Transitions are keyed off the issue, not the project: which moves are legal depends on where the ticket currently stands, so the list never offers a step Jira would reject.

Example output (list projects):

Typical AI agent workflow:

Create from Template

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

Examples:

View a Ticket

Examples:

Configure Credentials

Set up or update your Jira credentials and connection settings.

Check Status

Display current configuration and test connection to Jira.

Get 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:

🎯 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: [email protected]
• 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:

Batch Operations

Use shell scripting for batch operations:

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

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

No Projects Found

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

Permission Denied

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

Template Ticket Not Found

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

Invalid Project Override

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

Debug Information

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

• 📖 Documentation
• 🐛 Report Issues
• 💬 Discussions
• 📧 Contact

🧪 Development

Setup Development Environment

Project Structure

Running Tests

🤝 Contributing

We welcome contributions! Please follow these steps:

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

Code Style

This project follows PSR-12 coding standards:

🔒 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.5.0] - 2026-08-19

Added

• 🔀 update --status — move a ticket through its workflow by transition name, id or target status name, matched case-insensitively; unmatched values report what is legal from the current status, and asking for the status the ticket already has is a no-op
• 🔍 list transitions --issue=KEY — the transitions available from where the ticket stands, for scripts and AI agents

[1.4.0] - 2026-08-19

Added

• 💬 view --comments (-c) — appends the comment thread, oldest first, with author, date and an (edited …) marker; paginated, so long threads come back whole

Fixed

• 🐛 --version reported 1.0.0 on every release. The string was hardcoded when the CLI was written and never bumped; it now comes from Composer's installed version

[1.3.0] - 2026-08-19

Added

• 👀 view command — print a ticket's fields and description in the terminal, with --json for scripts and AI agents
• 🔤 AdfToText helper — converts Jira's ADF back to the Markdown flavour create and update accept, so a description survives a read/edit round trip

[1.2.0] - 2026-08-05

⚠️ Upgrade strongly recommended: 1.1.0 does not start on current Symfony.

Added

• ✏️ update command — modify summary, description, type, epic/parent, priority, assignee, labels and sprint on an existing ticket, interactively or by flag, with --dry-run
• 📎 Attachment upload on create, create-from and update via the repeatable --attachment flag, plus a wizard prompt
• 👤 --assignee (-a) in non-interactive mode, resolving display name, email, account id or me
• 📝 Markdown descriptions rendered as real Jira ADF — headings, bullet and ordered lists, bold, italic, inline code, links and hard breaks
• 🏷️ Labels prompted in the create wizard, and prefilled from the source ticket in create-from

Fixed

• 🐛 The CLI failed to start on symfony/console 6.0 and 7.4. Every command class redeclared $defaultName with a type the parent declares untyped, which is a fatal error in PHP. Only 7.3.x happened to work, so 1.1.0 is broken on a fresh install. Commands now use #[AsCommand]
• 🐛 Attachment uploads were never sent correctly. The request cleared its Content-Type with a null value, which makes Guzzle skip multipart/form-data, so the body went out with no boundary for the server to parse
• 🐛 --dry-run could create a real ticket. Without the non-interactive flags it fell through to the wizard, which ends by creating the ticket. It now fails up front
• 🐛 An ambiguous --assignee no longer silently picks the first partial match; it lists the candidates and stops
• 🐛 Issue types without a description no longer emit a PHP warning
• 🐛 getIssue() now requests the labels field

Internal

• ✅ Test suite grew from 31 to 114 tests; line coverage from ~19% to ~44%
• 🔌 JiraApiClient is injectable into the commands, and accepts an HTTP client, so the suite runs fully offline
• 🔁 The two duplicated assignee resolvers were merged into one tested helper
• ⚙️ CI now runs. It had never executed once: it triggered on main/develop while the default branch is master. Test Analytics and Codecov PR reporting are wired up

[1.1.0] - 2026-06-02

• 🤖 NEW: Non-interactive mode for create — pass all fields as flags, get issue key on stdout
• 🧪 NEW: --dry-run flag — preview the full JSON payload without creating any ticket
• 🔍 NEW: list command — outputs projects, issue-types, priorities, epics, and sprints as JSON
• 🏃 NEW: --sprint=active — auto-resolves the current active sprint at runtime
• 🐛 FIX: getEpics() migrated from deprecated /rest/api/3/search to /rest/api/3/search/jql

[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