Bragduck CLI

Transform your git commits 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 git commits 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

Installation

npm install -g @bragduck/cli

Usage

Quick Start

1. Install globally:

   npm install -g @bragduck/cli

2. Initialize and authenticate:

   bragduck init

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

3. Scan your commits:

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

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

4. 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 git commits and create brags with AI-powered refinement.

# Scan last 30 days (default)
bragduck scan

# Scan last 60 days
bragduck scan --days 60

# Include all commits (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 commits, not just current user's

Workflow:

1. Detects git repository
2. Fetches recent commits
3. Interactive checkbox selection
4. AI refines selected commits
5. Preview refined brags in table format
6. Confirm and create brags

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 apiBaseUrl
bragduck config get defaultCommitDays

# Set config value
bragduck config set defaultCommitDays 60
bragduck config set autoVersionCheck false
bragduck config set apiBaseUrl https://custom-api.example.com

Available Configuration Keys:

• apiBaseUrl - API base URL (default: https://api.bragduck.com)
• defaultCommitDays - Default days to scan (1-365, default: 30)
• autoVersionCheck - Automatic version checking (true/false, default: true)

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

Configuration

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

Available Settings

| Key | Type | Default | Description | |-----|------|---------|-------------| | apiBaseUrl | string | https://api.bragduck.com | API base URL | | defaultCommitDays | number | 30 | Default days to scan (1-365) | | autoVersionCheck | boolean | true | Automatic version checking |

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

No Commits Found

Problem: "No commits found in the last X days"

Solution:

# Increase the scan days
bragduck scan --days 90

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

API Connection Issues

Problem: Network or API errors

Solution:

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

# Check if custom API URL is correct
bragduck config get apiBaseUrl

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

| Script | Description | |--------|-------------| | npm run build | Build the project with tsup | | npm run dev | Build in watch mode for development | | npm test | Run test suite (122 tests) | | npm run test:coverage | Run tests with coverage report | | npm run test:ui | Run tests with interactive UI | | npm run lint | Lint code with ESLint | | npm run lint:fix | Lint and auto-fix issues | | npm run format | Format code with Prettier | | npm run typecheck | Type check without building |

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:

• ✅ 122 tests passing
• 📊 50% code coverage (focused on core logic)
• 🧪 7 test suites covering:
  • Services (Storage, Git, API)
  • 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)
│   └── 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)

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 PLAN.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