prflow

v1.0.1

Published

a month ago

AI-powered CLI tool for creating beautiful, template-aware pull requests

Downloads

0High
0Medium
0Low

hempun10

pr pull-request github cli ai automation developer-tools git conventional-commits

PRflow ✈️

AI-powered CLI for creating beautiful, template-aware pull requests

PRflow streamlines your pull request workflow by intelligently generating PR descriptions from your commits, filling in templates automatically, and remembering your team's preferences.

✨ Features

🤖 AI-Powered Descriptions - Generate PR descriptions using OpenAI, Anthropic, or local Ollama
📝 Template-Aware - Automatically detects and fills your PR template
🎫 Ticket Detection - Auto-detects Jira, Linear, GitHub Issues, and 6 more PM tools from branch names
🧠 Team Learning - Remembers your frequently used reviewers and labels
📋 Conventional Commits - Understands and leverages conventional commit format
👀 Preview Mode - Review your PR before creating
🔍 Dry Run - See what would happen without creating the PR
✅ Pre-flight Checks - Catch common mistakes before they happen
⚡ CI/CD Ready - Non-interactive mode for automation
✏️ Editor Integration - Edit descriptions in vim, nano, or VS Code
🔌 Offline Mode - Works without AI when needed

🚀 Quick Start

# Install globally
npm install -g prflow

# Or use npx (no install needed)
npx prflow

# Create a PR (from your feature branch)
prflow

# Or use the short alias
prf

📖 Usage

Create a Pull Request

# Basic usage - creates PR from current branch to main
prflow

# Specify base branch
prflow develop

# Create as draft
prflow --draft

# Preview before creating
prflow --preview

# Skip AI generation
prflow --no-ai

# Dry run - see what would be created
prflow create --dry-run

# Non-interactive mode (for CI/CD)
prflow create --yes --title "Auto PR" --body "Automated PR"

# Skip pre-flight checks
prflow create --skip-checks

# Verbose output
prflow create --verbose

All Create Options

prflow create [base] [options]

Options:
  -d, --draft                Create as draft PR
  -p, --preview              Preview PR before creating
  --no-ai                    Skip AI description generation
  -t, --title <title>        PR title
  -b, --body <body>          PR description body
  -a, --assignee <users...>  Assignees
  -r, --reviewer <users...>  Reviewers
  -l, --label <labels...>    Labels
  --dry-run                  Show what would be created without actually creating
  -y, --yes                  Non-interactive mode - use defaults
  --verbose                  Show detailed output
  --skip-checks              Skip pre-flight checks
  --update                   Update existing PR if one exists

Check PR Status

# Check if a PR exists for current branch
prflow status

# Open PR in browser
prflow open

Configuration

# Interactive configuration wizard
prflow config

# Show current configuration
prflow config --show

# Configure globally
prflow config --global

# Configure for current project
prflow config --local

# Clear team learning data
prflow config --clear-learning

Initialize in a Repository

# Create .prflowrc.json
prflow init

# Also create a PR template
prflow init --template

✅ Pre-flight Checks

Before creating a PR, prflow validates:

✓ Not on protected branch (main/master)
✓ No uncommitted changes
✓ Commits ahead of base branch
✓ GitHub token configured
✓ Remote repository configured
✓ Branch pushed to remote

# Example output when checks fail
❌ Pre-flight check failed:
1. You are on the base branch (main). Create a feature branch first:
   git checkout -b feature/my-feature

2. You have uncommitted changes. Please commit or stash them first:
   git add . && git commit -m "your message"

🎫 Project Management Integration

PRflow auto-detects tickets from your branch names:

| Tool | Branch Pattern | Detected | |------|---------------|----------| | Jira | feature/PROJ-123-desc | PROJ-123 | | Linear | fix/ENG-456-bug | ENG-456 | | GitHub Issues | feature/123-desc | #123 | | Shortcut | feature/sc-789-story | sc-789 | | ClickUp | fix/CU-abc123-task | CU-abc123 | | Azure DevOps | feature/AB#12345-work | AB#12345 | | Asana | Task IDs | Supported | | Trello | Card IDs | Supported | | Notion | Page IDs | Supported |

Configure your PM tool in .prflowrc.json:

{
  "projectManagement": {
    "tool": "jira",
    "baseUrl": "https://yourcompany.atlassian.net",
    "projectKey": "PROJ"
  }
}

⚙️ Configuration

PRflow looks for configuration in this order:

.prflowrc.json in current directory
.prflowrc.yaml in current directory
prflow key in package.json
Global ~/.prflowrc.json
Environment variables

Example Configuration

{
  "ai": {
    "provider": "openai",
    "model": "gpt-4o"
  },
  "editor": "vim",
  "defaults": {
    "assignSelf": true,
    "draft": false,
    "labels": [],
    "reviewers": []
  },
  "projectManagement": {
    "tool": "jira",
    "baseUrl": "https://company.atlassian.net"
  }
}

Environment Variables

| Variable | Description | |----------|-------------| | GITHUB_TOKEN | GitHub personal access token (required) | | GH_TOKEN | Alternative GitHub token variable | | OPENAI_API_KEY | OpenAI API key | | ANTHROPIC_API_KEY | Anthropic API key |

🤖 AI Providers

OpenAI (Default)

{
  "ai": {
    "provider": "openai",
    "model": "gpt-4o"
  }
}

Anthropic (Claude)

{
  "ai": {
    "provider": "anthropic",
    "model": "claude-sonnet-4-20250514"
  }
}

Ollama (Local - Free)

{
  "ai": {
    "provider": "ollama",
    "model": "llama3.2",
    "baseUrl": "http://localhost:11434"
  }
}

Offline Mode

{
  "ai": {
    "provider": "none"
  }
}

Or use the --no-ai flag:

prflow --no-ai

📝 PR Templates

PRflow automatically detects templates in these locations:

.github/PULL_REQUEST_TEMPLATE.md
.github/pull_request_template.md
PULL_REQUEST_TEMPLATE.md
docs/PULL_REQUEST_TEMPLATE.md

When a template is found, PRflow will:

Parse all sections (Description, Impact, etc.)
Detect checkboxes and type selections
Fill in content intelligently using AI
Preserve your template structure

🧠 Team Learning

PRflow remembers your preferences:

Reviewers - Frequently selected reviewers appear first with ⭐
Labels - Often-used labels are prioritized

Data is stored locally and persists across sessions.

🎯 Workflow Example

# 1. Create a feature branch with ticket
git checkout -b feature/PROJ-123-user-authentication

# 2. Make commits (conventional commits work best)
git commit -m "feat(auth): add JWT token validation"
git commit -m "feat(auth): implement login endpoint"
git commit -m "test(auth): add authentication tests"

# 3. Create PR with PRflow
prflow

# PRflow will:
# ✅ Detect ticket PROJ-123 from branch name
# ✅ Analyze your commits
# ✅ Generate AI description
# ✅ Fill in your PR template
# ✅ Link to Jira ticket
# ✅ Suggest relevant labels
# ✅ Show frequent reviewers first
# ✅ Create the PR with all metadata

🔧 CI/CD Integration

Use prflow in your CI pipelines:

# GitHub Actions example
- name: Create PR
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: |
    npx prflow create \
      --yes \
      --title "Auto: Update dependencies" \
      --body "Automated dependency update" \
      --label "dependencies" \
      --draft

🛠️ Development

# Clone the repository
git clone https://github.com/hempun10/test-pr-pilot.git
cd test-pr-pilot

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run in development
npm run dev

# Link for local testing
npm link

🧪 Testing

# Run all tests
npm test

# Watch mode
npm run test:watch