JiraFlow

A Command Line Interface (CLI) tool that deeply integrates with your Git workflow to automate Jira ticket management.

Overview

JiraFlow eliminates the friction of context switching between the terminal and the Jira web UI, allowing developers to stay focused and productive while keeping their project management system perfectly in sync. Turn tedious, multi-step Jira chores into single, intuitive commands.

Features

• 🚀 Start work on tickets - Automatically transition tickets and create properly named branches
• 📋 List assigned tickets - View your tickets without leaving the terminal
• 🔄 Submit for review - Push branches, update ticket status, and open pull requests
• 💬 Add comments - Update stakeholders directly from your terminal
• ✅ Mark tickets done - Complete workflows and optionally clean up branches
• 🔧 Configurable - Customize branch naming, status mappings, and Git hosts

Installation

npm install -g @deviloper-dev/jiraflow

Quick Start

1. Initialize your project:

   cd your-project
   jiraflow init

   This will prompt you for:

   • Jira credentials (email and API token)
   • Jira domain and project key
   • Git host (GitHub, GitLab, or Bitbucket)

2. Start working on a ticket:

   jiraflow start PROJ-123

3. Submit your work for review:

   jiraflow submit

4. Mark the ticket as done:

   jiraflow done

Commands

jiraflow init

Initializes a new JiraFlow project in the current directory.

Options:

• -r, --reauth - Force re-authentication even if credentials exist

Example:

jiraflow init
jiraflow init --reauth  # Re-authenticate with new credentials

jiraflow list

Display a list of Jira tickets assigned to you.

Example:

jiraflow list

jiraflow start <ticket-id>

Start work on a Jira ticket by transitioning it to "In Progress" and creating a branch.

Example:

jiraflow start PROJ-123

This command will:

• Validate the ticket exists and you have access
• Move the ticket to "In Progress" status
• Create and checkout a new branch with a descriptive name
• Save the ticket context for other commands

jiraflow submit

Submit your work for review by pushing the branch and transitioning the ticket.

Example:

jiraflow submit

This command will:

• Check for uncommitted changes (and abort if found)
• Push the current branch to remote
• Move the ticket to "In Review" status
• Open a pull request URL in your browser

jiraflow comment "<message>"

Add a comment to the current Jira ticket.

Examples:

jiraflow comment "Fixed the login issue"
jiraflow comment  # Opens editor for multi-line comment

jiraflow done

Mark the current ticket as done and optionally clean up branches.

Example:

jiraflow done

This command will:

• Move the ticket to "Done" status
• Prompt to delete the local and remote branch
• Clear the ticket context

Configuration

Local Configuration (.jflow.json)

Created in your project directory:

{
  "projectKey": "PROJ",
  "jiraDomain": "your-company.atlassian.net",
  "gitHost": "github",
  "branchTemplate": "feature/{{ticketId}}-{{ticketSummary_slug}}",
  "statusMappings": {
    "start": "In Progress",
    "review": "In Review", 
    "done": "Done"
  }
}

Global Configuration

Your Jira credentials are stored securely using the conf library in your system's config directory.

Setting up Jira API Token

1. Go to Atlassian Account Settings
2. Click "Create API token"
3. Give it a label (e.g., "JiraFlow CLI")
4. Copy the generated token
5. Use this token when running jiraflow init

Branch Naming

JiraFlow uses configurable templates for branch names. The default template is:

feature/{{ticketId}}-{{ticketSummary_slug}}

This creates branches like: feature/PROJ-123-implement-user-authentication

Supported Git Hosts

• GitHub - Creates pull request URLs with pre-filled title and description
• GitLab - Creates merge request URLs with pre-filled information
• Bitbucket - Creates pull request URLs with pre-filled information

Error Handling

JiraFlow provides clear, actionable error messages:

• Authentication issues: Suggests running jiraflow init --reauth
• Network problems: Clear connectivity error messages
• Git repository issues: Ensures commands run in Git repositories
• Ticket state conflicts: Explains valid transitions

Troubleshooting

"Could not connect to Jira"

• Check your internet connection
• Verify your Jira domain in .jflow.json
• Ensure your API token is still valid

"Authentication failed"

Run jiraflow init --reauth to update your credentials.

"Not in a Git repository"

Make sure you're running commands from within a Git repository.

"Could not determine the Jira ticket"

This happens when JiraFlow can't find ticket context. Run jiraflow start <ticket-id> to establish context.

Development

# Clone the repository
git clone https://github.com/iyogeshjoshi/jiraflow.git
cd jiraflow

# Install dependencies
npm install

# Build the project
npm run build

# Run locally
./bin/run.js --help

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Copyright (c) 2025 Yogesh Joshi. All rights reserved.

Support

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 📖 Documentation: GitHub Wiki