prtool

A command-line tool that fetches GitHub pull requests (PRs) for a specified time period and scope (organization, team, user, or repository), summarizes them using an LLM (OpenAI or Ollama), and outputs the result in Markdown format.

Features

• Multi-scope PR fetching: Fetch PRs from organizations, teams, users, or specific repositories
• Time-based filtering: Filter PRs by merge date using relative time ranges (-7d, -1m, -1yr)
• AI-powered summaries: Generate intelligent summaries using OpenAI or Ollama
• Multiple output formats: Output to stdout or save to files
• Flexible configuration: Configure via YAML files, environment variables, or CLI flags
• CI/CD friendly: Special mode for automated environments
• Dry-run support: Preview data without generating summaries

Installation

From Source

Requires Go 1.24 or later.

git clone https://github.com/willis7/prtool.git
cd prtool
go build -o prtool ./main.go

Binary Releases

Download pre-built binaries for Linux, macOS, and Windows from the releases page.

From a Snapshot (local testing)

You can build a snapshot using GoReleaser without publishing:

make snapshot

Artifacts will appear in dist/ with a dev-<commit> version.

Quick Start

1. Generate Configuration File

prtool init

This creates a .prtool.yaml file with all available configuration options and comments.

2. Configure GitHub Token

Set your GitHub personal access token:

export PRTOOL_GITHUB_TOKEN="your_github_token_here"

Or edit the .prtool.yaml file:

github_token: "your_github_token_here"

3. Fetch PRs

# Fetch PRs from a user for the last 7 days
prtool --user=octocat --since=-7d

# Fetch PRs from an organization for the last month
prtool --org=github --since=-1m

# Fetch PRs from a specific repository
prtool --repo=owner/repository --since=-2w

Usage Examples

Basic Usage

# Fetch PRs from user 'octocat' for the last week
prtool --user=octocat --since=-7d

# Fetch PRs from organization 'github' for the last month
prtool --org=github --since=-1m

# Fetch PRs from specific repository
prtool --repo=microsoft/vscode --since=-14d

# Fetch PRs from team (format: org/team)
prtool --team=github/docs --since=-1w

AI Summary Generation

# Use OpenAI for AI summaries
prtool --user=octocat --llm-provider=openai --llm-api-key=sk-...

# Use Ollama (local)
prtool --user=octocat --llm-provider=ollama --llm-model=llama3.2

# Skip AI summary generation (dry-run) - outputs PR data in table format
prtool --user=octocat --dry-run

Output Options

# Save to file
prtool --user=octocat --output=report.md

# Verbose logging
prtool --user=octocat --verbose

# Log to file
prtool --user=octocat --log-file=prtool.log

# CI-friendly mode (no progress indicators)
prtool --user=octocat --ci

Configuration File

Create a configuration file with prtool init, then customize:

# .prtool.yaml
github_token: "ghp_xxxxxxxxxxxx"
user: "octocat"
since: "-7d"
llm_provider: "openai"
llm_api_key: "sk-xxxxxxxxxxxx"
llm_model: "gpt-3.5-turbo"
output: "weekly-report.md"
verbose: true

Then run simply:

prtool

Logging

prtool provides flexible logging options for different use cases:

Console Logging

Use --verbose to enable detailed logging to the console:

prtool --user=octocat --verbose

File Logging

Log to a file using --log-file:

prtool --user=octocat --log-file=prtool.log

Combine with --verbose for both console and file logging:

prtool --user=octocat --verbose --log-file=prtool.log

CI Mode Logging

In CI environments, use --ci to suppress progress indicators while still allowing error logging.

Configuration

Configuration can be provided via:

1. Command-line flags (highest precedence)
2. Environment variables
3. YAML configuration file (lowest precedence)

CLI Flags

Flag	Description	Example
--github-token	GitHub personal access token	--github-token=ghp_xxx
--org	GitHub organization	--org=github
--team	GitHub team (org/team)	--team=github/docs
--user	GitHub user	--user=octocat
--repo	GitHub repository (owner/repo)	--repo=owner/repo
--since	Time range for PRs	--since=-7d
--llm-provider	LLM provider (stub/openai/ollama)	--llm-provider=openai
--llm-api-key	LLM API key	--llm-api-key=sk-xxx
--llm-model	LLM model name	--llm-model=gpt-4
--output	Output file path	--output=report.md
--dry-run	Skip LLM processing	--dry-run
--verbose	Enable verbose logging	--verbose
--ci	CI-friendly mode	--ci
--log-file	Log file path	--log-file=app.log

Environment Variables

All flags have corresponding environment variables with the PRTOOL_ prefix:

export PRTOOL_GITHUB_TOKEN="ghp_xxxxxxxxxxxx"
export PRTOOL_USER="octocat"
export PRTOOL_SINCE="-7d"
export PRTOOL_LLM_PROVIDER="openai"
export PRTOOL_LLM_API_KEY="sk-xxxxxxxxxxxx"
export PRTOOL_VERBOSE="true"

Time Range Format

Format	Description	Example
-7d	Last 7 days	--since=-7d
-2w	Last 2 weeks	--since=-2w
-1m	Last 1 month	--since=-1m
-3mo	Last 3 months	--since=-3mo
-1yr	Last 1 year	--since=-1yr

LLM Providers

OpenAI

prtool --llm-provider=openai --llm-api-key=sk-xxx --llm-model=gpt-3.5-turbo

Supported models (defaults to gpt-3.5-turbo if not specified):

• gpt-3.5-turbo
• gpt-4
• gpt-4-turbo
• Any other OpenAI model name

Ollama (Local)

First, start Ollama locally:

ollama serve
ollama pull llama3.2

Then use with prtool:

prtool --llm-provider=ollama --llm-model=llama3.2

Supported models (defaults to llama3.2 if not specified):

• llama3.2
• Any other Ollama model you've pulled locally

Stub (Testing)

prtool --llm-provider=stub

Returns a fixed summary for testing purposes.

CI/CD Usage

For automated environments and CI/CD pipelines, use the --ci flag:

prtool --user=octocat --since=-7d --output=report.md --ci

CI mode is designed for non-interactive environments and:

• Suppresses progress indicators and spinners that don't work well in CI logs
• Uses clean exit codes (0 for success, 1 for failure)
• Reduces verbose output for cleaner, more readable CI logs
• Fails fast on configuration errors rather than prompting for input

Commands

prtool (default)

Fetch and summarize pull requests.

prtool init

Generate a sample configuration file (.prtool.yaml) in the current directory.

prtool init

prtool completion [bash|zsh|fish|powershell]

Generate shell completion script for the specified shell.

Version Commands

# Show current version
prtool --version

# Show detailed version information including build metadata
prtool --version --verbose

# Check for latest version on GitHub
prtool --version-check

Authentication

Create a GitHub Personal Access Token with the following permissions:

• repo (for private repositories)
• public_repo (for public repositories)
• read:org (for organization access)

Set the token via:

1. Environment variable: export PRTOOL_GITHUB_TOKEN="ghp_xxx"
2. Configuration file: github_token: "ghp_xxx"
3. Command line: --github-token=ghp_xxx

Shell Completion

prtool supports shell completion for bash, zsh, fish, and PowerShell.

Bash

# Add to ~/.bashrc or ~/.bash_profile
source <(prtool completion bash)

# Or install globally
prtool completion bash > /etc/bash_completion.d/prtool

Zsh

# Add to ~/.zshrc
source <(prtool completion zsh)

# Or for oh-my-zsh users
prtool completion zsh > "${fpath[1]}/_prtool"

Fish

prtool completion fish > ~/.config/fish/completions/prtool.fish

PowerShell

# Add to PowerShell profile
prtool completion powershell >> $PROFILE

Examples

Weekly Team Report

# Generate weekly report for a team
prtool --team=myorg/backend --since=-7d --output=weekly-report.md --llm-provider=openai

# With configuration file
echo "team: myorg/backend
since: -7d
output: weekly-report.md
llm_provider: openai
llm_api_key: sk-xxx" > .prtool.yaml

prtool

Monthly Organization Summary

prtool --org=mycompany --since=-1m --llm-provider=ollama --verbose

Individual Contributor Report

prtool --user=developer --since=-2w --dry-run

Troubleshooting

Common Issues

Error: GitHub token is required

• Set your GitHub token via environment variable, config file, or CLI flag

Error: No pull requests found

• Check your scope (org/team/user/repo) and time range
• Verify you have access to the specified repositories

OpenAI API error

• Verify your API key is correct
• Check you have sufficient credits/quota

Ollama connection failed

• Ensure Ollama is running locally (ollama serve)
• Verify the model is installed (ollama pull llama3.2)

Debug Mode

Use verbose logging to troubleshoot:

prtool --user=octocat --verbose --log-file=debug.log

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Release Process

Releases are automated with GoReleaser.

Prerequisites

• Ensure you have a clean git tree and all tests pass.
• Install GoReleaser locally (optional for snapshot):

  go install github.com/goreleaser/goreleaser/v2@latest

Create a Release

1. Decide the next semantic version (e.g. v0.2.0).
2. Update any docs if needed.
3. Tag and push:

   git tag v0.2.0
   git push origin v0.2.0

4. GitHub Actions will run the release workflow and publish binaries, checksums, SBOM, and Homebrew formula.

Local Snapshot

Generate unsigned snapshot artifacts locally without publishing:

make snapshot

Full Local Release Dry Run

goreleaser release --snapshot --skip=publish,sign --clean

Viewing Build Metadata

./prtool --version --verbose

This prints the version plus commit, build date, and builder.

License

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