Goblin CLI

A fast, interactive TUI (Text User Interface) tool to analyze GitHub Pull Requests and discover all merged PRs referenced within them.

Table of Contents

• Overview
• Features
• Installation
• Authentication
• Usage
• How It Works
• Interactive Controls
• Output Format
• Accessibility
• Architecture
• Troubleshooting
• Requirements
• License

Overview

Goblin CLI is a command-line tool that helps you understand PR dependencies by analyzing GitHub Pull Requests and extracting all other PRs that were merged into them. This is particularly useful for:

• Understanding what changes are included in a large PR
• Tracking dependencies between PRs
• Generating reports of merged work
• Code review workflows

Features

✨ Interactive TUI - Beautiful terminal interface built with Ink (React for CLIs)

🔍 Three Powerful Modes:

• PR Analyzer - Find all PRs merged into a specific PR
• Branch Comparison - See what's going live (compare patch → main)
• PR Status Checker - Check if a PR is live in production

🔑 Flexible Authentication - Supports multiple authentication methods:

• GitHub CLI (gh) credentials (automatic)
• GITHUB_TOKEN environment variable
• GH_TOKEN environment variable
• Built-in setup instructions when not authenticated

📊 Real-time Connection Status - See your GitHub username and API rate limits in all screens

⚙️ Local Settings - Save default organization for faster workflow:

• goblin config set-org rocketium-labs
• Then use just goblin compare my-repo instead of goblin compare rocketium-labs/my-repo

🚀 Smart Batching - 80% faster with intelligent PR reference parsing from commit messages

♿ WCAG Compliant - High-contrast, accessible design following WCAG2ICT guidelines

🎯 Multiple Input Formats - Accepts PR URLs, owner/repo, or just repo (with default org)

🔄 Continuous Workflow - Query multiple PRs in one session with mode switching (ESC to switch, Q to quit)

Installation

Via npm (Recommended)

npm install -g @rocketium-labs/goblin-cli

Via Homebrew (macOS/Linux)

brew tap rocketium/goblin
brew install goblin

From Source

# Clone the repository
git clone https://github.com/rocketium/goblin-cli.git
cd goblin-cli

# Install dependencies
npm install

# Build the project
npm run build

# Link globally
npm link

Authentication

Goblin CLI supports multiple authentication methods, tried in this order:

1. GitHub CLI (Recommended)

If you already use the gh CLI tool, Goblin will automatically use your credentials.

# Check if you're authenticated
gh auth status

# If not, authenticate
gh auth login

2. Environment Variables

Set one of these environment variables:

# Option 1: GITHUB_TOKEN
export GITHUB_TOKEN="ghp_your_token_here"

# Option 2: GH_TOKEN
export GH_TOKEN="ghp_your_token_here"

Creating a GitHub Personal Access Token

1. Go to GitHub Settings → Developer settings → Personal access tokens
2. Click "Generate new token" (classic)
3. Give it a descriptive name (e.g., "Goblin CLI")
4. Select the repo scope (required for accessing PR data)
5. Click "Generate token"
6. Copy the token and save it securely
7. Export it as an environment variable (see above)

Note: Never commit tokens to version control or share them publicly.

Usage

Mode Selector (Recommended)

Run Goblin without arguments to see the mode selector:

goblin

Choose from three modes:

• Branch comparison - What is going live? (compare patch > main)
• PR status checker - Is this PR live?
• PR analyzer - Find all PRs merged into a specific PR

Navigate with ↑↓ arrows, press ENTER to select, ESC to go back, Q to quit.

Direct Commands

1. Branch Comparison

Compare two branches to see what PRs are going live:

# Default: compare patch vs main
goblin compare owner/repo

# With default org set:
goblin compare my-repo

# Custom branches
goblin compare owner/repo --base production --head staging

# Custom delay between API calls (default: 1000ms)
goblin compare owner/repo --delay 500

2. PR Status Checker

Check if a PR is merged in specific branches:

# Check if PR is in patch and main
goblin check owner/repo 123

# Custom branches
goblin check owner/repo 123 --branches patch,main,production

# With full URL
goblin check https://github.com/owner/repo/pull/123

3. PR Analyzer

Find all PRs merged into a specific PR:

# Using a full GitHub PR URL
goblin https://github.com/FFmpeg/FFmpeg/pull/315

# Using owner/repo/number format
goblin FFmpeg FFmpeg 315

# Or run without arguments to enter interactive mode
goblin

Configuration Commands

Save your default organization for faster workflow:

# Set default organization
goblin config set-org rocketium-labs

# Now you can use just the repo name
goblin compare my-repo
# (instead of: goblin compare rocketium-labs/my-repo)

# View current default org
goblin config get-org

# Clear default org
goblin config clear-org

Settings are saved in ~/.goblin/config.json

Development Mode

When developing or testing:

# Run without building
npm run dev

# Run in interactive mode
npm run dev

# Run with a specific PR
npm run dev https://github.com/owner/repo/pull/123

How It Works

Analysis Process

1. Authentication: Validates GitHub credentials
2. PR Fetch: Retrieves the target PR using GitHub's REST API
3. Commit Analysis: Fetches all commits in the PR
4. Pattern Matching: Scans commit messages and PR description for PR references (e.g., #123)
5. Verification: Checks if referenced PRs have been merged
6. Report Generation: Displays formatted results with PR details

PR Reference Detection

Goblin detects PR references in:

• Commit messages: Fix bug (#456), Merge pull request #789
• PR descriptions: Depends on #321, Fixes #654

The tool uses regex pattern matching to find #<number> references and validates them against the GitHub API.

Interactive Controls

Input Screen

• Type PR URL or owner repo pr_number
• ENTER - Submit query
• ESC - Quit application

Results Screen

• ENTER - Start new query
• Q - Quit application
• ESC - Quit application

Output Format

Example Output

GitHub PR Analyzer
─────────────────────────────────────────

PR Analysis Report
═══════════════════════════════════════════════════════════════

Main PR:
  #315 - Add new feature for user authentication
  Author: johndoe
  URL: https://github.com/owner/repo/pull/315

Merged PRs found: 3

#12340 - Fix login bug
  Author: janedoe
  URL: https://github.com/owner/repo/pull/12340

#12342 - Update authentication library
  Author: developer123
  URL: https://github.com/owner/repo/pull/12342

#12344 - Add unit tests for auth
  Author: tester456
  URL: https://github.com/owner/repo/pull/12344

Press ENTER for new query • Press Q or ESC to quit

Output Fields

For each PR (main and merged), Goblin displays:

• PR Number: GitHub PR identifier (e.g., #315)
• Title: Full PR title
• Author: GitHub username of the PR author
• URL: Direct link to the PR on GitHub

Accessibility

Goblin CLI follows WCAG 2.1 Level AAA guidelines for terminal applications:

• High Contrast: Uses default terminal colors (white/black) for maximum contrast
• No Color Dependency: Information hierarchy conveyed through bold text, not color
• Screen Reader Compatible: Semantic text structure
• Keyboard Navigation: Full keyboard control, no mouse required
• Clear Labels: Explicit instructions at each step

Works well with:

• Light and dark terminal themes
• Color blindness
• Screen readers
• Low vision settings

Architecture

Project Structure

goblin-cli/
├── src/
│   ├── index.ts       # CLI entry point, command parsing
│   ├── github.ts      # GitHub API client, authentication
│   └── ui.tsx         # TUI interface (React/Ink)
├── dist/              # Compiled JavaScript output
├── package.json       # Dependencies and scripts
├── tsconfig.json      # TypeScript configuration
└── README.md          # This file

Technology Stack

• TypeScript: Type-safe development
• React + Ink: Terminal UI framework
• Octokit: Official GitHub REST API client
• Commander: CLI argument parsing
• ink-text-input: Text input component

Key Components

GitHubClient (src/github.ts)

• Handles authentication (gh CLI, env variables)
• Fetches PR details via GitHub API
• Analyzes commits and PR descriptions
• Validates merged PRs

PRAnalyzer (src/ui.tsx)

• Interactive TUI interface
• State management for input/results
• Keyboard event handling
• Display formatting

Troubleshooting

"GitHub token not found"

Problem: Goblin can't find your GitHub credentials.

Solutions:

1. Run gh auth login to authenticate with GitHub CLI
2. Set GITHUB_TOKEN or GH_TOKEN environment variable
3. Verify token has repo scope

"command not found: goblin"

Problem: Global installation didn't work.

Solutions:

1. Run npm link in the project directory
2. Check npm's global bin directory is in your PATH:

   npm config get prefix
   # Add /bin to your PATH if needed

3. Use npm run dev instead

PR references not found

Problem: Goblin shows "0 merged PRs found" when you expect results.

Possible Reasons:

1. PR references might use different format (e.g., owner/repo#123 instead of #123)
2. Referenced PRs might not be merged yet
3. References might be in code comments, not commit messages or PR description

Note: Goblin only detects #<number> format in commits and PR descriptions, not in code changes.

API Rate Limiting

Problem: "API rate limit exceeded" error.

Solution:

• Authenticated requests have a limit of 5,000/hour
• Wait for the rate limit to reset
• Use a different GitHub account/token if needed

Build Errors

Problem: TypeScript compilation fails.

Solutions:

1. Delete node_modules and dist folders
2. Run npm install again
3. Ensure Node.js version is 18 or higher:

   node --version

Requirements

System Requirements

• Node.js: 18.x or higher
• npm: 8.x or higher
• OS: macOS, Linux, or Windows (with WSL recommended)

GitHub Requirements

• Authentication: GitHub personal access token or gh CLI
• Permissions: repo scope for accessing PR data
• Network: Internet connection to GitHub API

Terminal Requirements

• Terminal with UTF-8 support
• Minimum width: 80 characters (recommended)

Development

Scripts

# Build TypeScript to JavaScript
npm run build

# Run in development mode (with tsx)
npm run dev

# Run built version
npm start

# Link globally for testing
npm link

# Unlink global installation
npm unlink -g goblin-cli

Making Changes

1. Edit source files in src/
2. Run npm run build to compile
3. Test with npm run dev or goblin (if linked)

Code Structure

• src/index.ts: Entry point, uses Commander for CLI
• src/github.ts: Pure logic, no UI dependencies
• src/ui.tsx: React components, Ink rendering

Contributing

Contributions are welcome! Areas for improvement:

• Support for GitLab, Bitbucket
• Export reports to JSON/CSV
• Filter PRs by author, date, labels
• Recursively analyze nested PR dependencies
• Configuration file support

License

ISC License - see LICENSE file for details

Credits

Built with:

• Ink by Vadim Demedes
• Octokit by GitHub
• Commander.js by TJ Holowaychuk

Support

For issues, questions, or suggestions, please open an issue on GitHub.

Author: Created with Claude Code Version: 1.0.0