Bragduck CLI

Transform your GitHub Pull Requests into polished achievements with AI-powered refinement

Overview

Bragduck CLI is a powerful command-line tool that helps developers track and showcase their achievements by transforming GitHub Pull Requests into polished "brags" using AI-powered refinement. Perfect for updating your portfolio, preparing for performance reviews, or simply keeping track of your accomplishments.

Why Bragduck?

• 🤖 AI-Powered: Automatically refines your commit messages into professional achievements
• 🎯 Context-Aware: Analyzes commit diffs, file changes, and patterns
• 🔒 Secure: OAuth authentication with encrypted credential storage
• 🎨 Beautiful UI: Interactive terminal experience with colors and spinners
• 🚀 Fast: Optimized build size (69KB) for quick installation and execution
• 🌐 Cross-Platform: Works on macOS, Windows, and Linux

Prerequisites

Before installing Bragduck CLI, you need:

1. Node.js ≥18.0.0

   node --version  # Should be v18.0.0 or higher

2. GitHub CLI (gh)

   # macOS
   brew install gh
   
   # Windows
   winget install --id GitHub.cli
   
   # Linux
   # See https://github.com/cli/cli#installation

3. Authenticate with GitHub CLI

   gh auth login

   Follow the prompts to authenticate with your GitHub account.

Installation

npm install -g @bragduck/cli

Usage

Quick Start

1. Install GitHub CLI and authenticate:

   # Install GitHub CLI (if not already installed)
   brew install gh  # macOS
   
   # Authenticate with GitHub
   gh auth login

2. Install Bragduck CLI globally:

   npm install -g @bragduck/cli

3. Initialize and authenticate:

   bragduck init

   This opens your browser for OAuth authentication. Once completed, your credentials are securely stored.

4. Scan your merged PRs:

   cd /path/to/your/github/repo
   bragduck scan

   Select PRs interactively, preview AI-refined brags, and create them.

5. View your brags:

   bragduck list

Commands

bragduck init

Authenticate with Bragduck using OAuth. Opens your browser for authentication and securely stores credentials.

bragduck init

bragduck scan

Scan merged GitHub Pull Requests and create brags with AI-powered refinement.

# Scan last 30 days (default, your PRs only)
bragduck scan

# Scan last 60 days
bragduck scan --days 60

# Include all PRs (not just yours)
bragduck scan --all

# Combine options
bragduck scan --days 90 --all

Options:

• -d, --days <number> - Number of days to scan (default: 30)
• -a, --all - Include all PRs, not just current user's

Workflow:

1. Validates GitHub repository
2. Fetches merged PRs in timeframe (filtered by author unless --all)
3. Displays PRs in format: #123 PR Title [stats]
4. Interactive checkbox selection
5. AI refines selected PRs (using title + description)
6. Preview refined brags in table format
7. Confirm and create brags

What gets scanned:

• ✅ Merged Pull Requests only
• ✅ PR title and description used for context
• ✅ Aggregate PR statistics (files changed, insertions, deletions)
• ✅ Filtered by PR author (person who created the PR)
• ❌ Draft or closed-without-merge PRs excluded
• ❌ Individual commits not scanned

Requirements:

• Must be in a GitHub repository (GitLab/Bitbucket not supported)
• GitHub CLI must be installed and authenticated (gh auth login)

bragduck list

List your existing brags with filtering and pagination.

# List all brags (default: 50)
bragduck list

# Show 25 brags
bragduck list --limit 25

# Show next page (skip first 50)
bragduck list --offset 50

# Filter by tags
bragduck list --tags "feature,bugfix"

# Search by keyword
bragduck list --search "implemented authentication"

# Combine filters
bragduck list --tags "feature" --search "API" --limit 20

Options:

• -l, --limit <number> - Number of brags to display (default: 50)
• -o, --offset <number> - Number of brags to skip (default: 0)
• -t, --tags <tags> - Filter by tags (comma-separated)
• -s, --search <query> - Search brags by keyword

bragduck config

Manage CLI configuration.

# List all configuration values
bragduck config list

# Get specific config value
bragduck config get defaultCommitDays

# Set config value
bragduck config set defaultCommitDays 60
bragduck config set autoVersionCheck false

Available Configuration Keys:

• defaultCommitDays - Default days to scan (1-365, default: 30)
• autoVersionCheck - Automatic version checking (true/false, default: true)

Note: The API base URL is set to https://api.bragduck.com by default. You can override it using the API_BASE_URL environment variable if needed for custom deployments.

bragduck logout

Clear stored credentials from your system.

bragduck logout

Global Options

Available for all commands:

# Enable debug mode (shows detailed logs)
bragduck --debug <command>

# Skip automatic version check
bragduck --skip-version-check <command>

# Show version
bragduck --version

# Show help
bragduck --help

Features

Core Features

• 🔐 OAuth Authentication - Secure authentication with local callback server
• 🤖 AI-Powered Refinement - Transforms commit messages into professional achievements
• ✅ Interactive Selection - Checkbox interface for selecting commits
• 📊 Rich Preview - Table preview of refined brags before creation
• 🔍 Smart Filtering - Filter brags by tags and search keywords
• 📄 Pagination Support - Handle large numbers of brags efficiently

Technical Features

• 🔒 Secure Storage - Encrypted credential storage with AES-256-GCM
• 🎨 Beautiful UI - Colorful terminal output with spinners and tables
• 🔄 Auto-Updates - Automatic version checking with update notifications
• 🐛 Debug Mode - Detailed logging for troubleshooting
• ⚙️ Configurable - Customize API URL, scan days, and more
• 🚀 Lightweight - Only 69KB build size
• ✨ TypeScript - Fully typed for better IDE support

Platform Support

• ✅ macOS (Tested)
• ✅ Windows (Compatible)
• ✅ Linux (Compatible)
• ✅ Node.js ≥18.0.0
• ✅ GitHub repositories only (GitLab/Bitbucket not supported)

Configuration

Configuration is stored in ~/.config/bragduck/config.json (or equivalent on your OS).

Available Settings

API Base URL: The CLI connects to https://api.bragduck.com by default. For custom deployments, set the API_BASE_URL environment variable.

Credentials Storage

Credentials are encrypted and stored at:

• File: ~/.bragduck/credentials.enc
• Encryption: AES-256-GCM with machine-specific key derivation
• Access: Only accessible by the CLI on your machine

Troubleshooting

Authentication Issues

Problem: "Not authenticated" error when running commands

Solution:

# Re-authenticate
bragduck logout
bragduck init

Git Repository Not Found

Problem: "Not a git repository" error

Solution:

# Make sure you're in a git repository
cd /path/to/your/git/repo
git status  # Verify it's a git repo
bragduck scan

GitHub CLI Not Authenticated

Problem: "Not authenticated with GitHub" error

Solution:

# Authenticate with GitHub CLI
gh auth login

# Verify authentication
gh auth status

Not a GitHub Repository

Problem: "This repository is not hosted on GitHub" error

Solution:

• Bragduck CLI currently only supports GitHub repositories
• Make sure you're in a repository with a GitHub remote:

git remote -v  # Should show github.com URL

No Merged PRs Found

Problem: "No merged PRs found in the last X days"

Solution:

# Increase the scan days
bragduck scan --days 90

# Or include all PRs (not just yours)
bragduck scan --all

# Check if you have merged PRs on GitHub
gh pr list --state merged --limit 10

GitHub CLI Not Installed

Problem: "GitHub CLI (gh) is not installed" error

Solution:

# macOS
brew install gh

# Windows
winget install --id GitHub.cli

# Linux - see https://github.com/cli/cli#installation

# Verify installation
gh --version

API Connection Issues

Problem: Network or API errors

Solution:

# Check your internet connection
# Try with debug mode to see detailed logs
bragduck --debug scan

Version Check Failures

Problem: Version check taking too long or failing

Solution:

# Skip version check for this run
bragduck --skip-version-check scan

# Or disable it permanently
bragduck config set autoVersionCheck false

Enable Debug Mode

For any issues, enable debug mode to see detailed logs:

bragduck --debug <command>

This shows:

• API requests and responses
• Authentication status
• Configuration reads/writes
• Internal operations

Development

Prerequisites

• Node.js ≥ 18.0.0
• npm or yarn

Setup

# Clone the repository
git clone https://github.com/medhatdawoud/bragduck-cli.git
cd bragduck-cli

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint

# Format code
npm run format

Project Structure

bragduck-cli/
├── src/
│   ├── commands/      # CLI commands
│   ├── services/      # Business logic services
│   ├── ui/            # Terminal UI components
│   ├── types/         # TypeScript type definitions
│   ├── utils/         # Utility functions
│   └── cli.ts         # CLI entry point
├── tests/             # Test files
├── dist/              # Built files
└── package.json

Scripts

Testing

The project has comprehensive test coverage:

# Run all tests
npm test

# Run with coverage report
npm run test:coverage

# Run specific test file
npx vitest run tests/commands/config.test.ts

# Run in watch mode
npx vitest

Test Stats:

• ✅ 126 tests passing
• 📊 50% code coverage (focused on core logic)
• 🧪 8 test suites covering:
  • Services (Storage, Git, API, GitHub)
  • Commands (Config, List)
  • Utilities (Version, Errors)

Architecture

src/
├── commands/       # CLI command implementations
│   ├── init.ts     # OAuth authentication flow
│   ├── scan.ts     # Main feature - commit scanning
│   ├── list.ts     # List brags with filtering
│   ├── config.ts   # Configuration management
│   └── logout.ts   # Credential cleanup
├── services/       # Business logic services
│   ├── auth.service.ts     # Authentication & token management
│   ├── api.service.ts      # Backend API client (ofetch)
│   ├── git.service.ts      # Git operations (simple-git)
│   ├── github.service.ts   # GitHub PR fetching (gh CLI)
│   └── storage.service.ts  # Encrypted credential storage
├── ui/             # Terminal UI components
│   ├── prompts.ts      # Interactive prompts (Inquirer)
│   ├── formatters.ts   # Output formatting (chalk, cli-table3)
│   └── spinners.ts     # Loading indicators (ora)
├── utils/          # Utility functions
│   ├── errors.ts       # Custom error classes
│   ├── logger.ts       # Logging utility
│   ├── version.ts      # Version checking & comparison
│   ├── validators.ts   # Input validation
│   ├── browser.ts      # Cross-platform browser opening
│   └── oauth-server.ts # Local OAuth callback server
└── types/          # TypeScript type definitions

Tech Stack

Core:

• TypeScript 5.x
• Node.js ≥18.0.0
• Commander.js (CLI framework)

Build & Test:

• tsup (TypeScript bundler with esbuild)
• Vitest (testing framework)
• ESLint + Prettier

Dependencies:

• @inquirer/prompts (interactive UI)
• simple-git (Git operations)
• ofetch (HTTP client)
• chalk, ora, cli-table3, boxen (terminal styling)
• conf (configuration management)

External Tools:

• GitHub CLI (gh) - Required for PR scanning

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Quick Contribution Guide

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

Development Guidelines

• Write tests for new features
• Follow existing code style (ESLint + Prettier)
• Update documentation for user-facing changes
• Keep commits atomic and well-described

Support

Getting Help

• 📖 Documentation: Read this README and TESTING_GUIDE.md
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

Reporting Issues

When reporting issues, please include:

1. Environment: OS, Node.js version, npm version
2. Steps to reproduce: Clear steps to reproduce the issue
3. Expected behavior: What you expected to happen
4. Actual behavior: What actually happened
5. Debug output: Run with --debug flag and include output

Example:

bragduck --debug scan

License

MIT License - see LICENSE file for details

Acknowledgments

Built with ❤️ using:

• Commander.js - CLI framework
• Inquirer.js - Interactive prompts
• simple-git - Git operations
• Vitest - Testing framework
• And many other great open-source projects

Made by Medhat Dawoud | Powered by AI