Bragduck CLI

Part of the BragDuck monorepo. Run all commands from the monorepo root unless noted otherwise.

Sync work items from GitHub, GitLab, Bitbucket, Jira, and Confluence into polished achievements with AI-powered refinement

Overview

Bragduck CLI helps developers track and showcase their achievements by syncing work items from multiple sources (GitHub, GitLab, Bitbucket, Jira, Confluence) and refining them into polished "brags" using AI. Perfect for performance reviews, portfolio updates, or keeping track of accomplishments.

Why Bragduck?

• Multi-Source Sync: Pull work items from GitHub, GitLab, Bitbucket, Jira, and Confluence
• AI-Powered: Automatically refines work items into professional achievements
• Context-Aware: Analyzes PRs, issues, and project data for meaningful brags
• Secure: OAuth and token-based authentication with encrypted credential storage
• Beautiful UI: Interactive terminal experience with colors and spinners
• 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

As a global tool (end users)

npm install -g @bragduck/cli

For development (monorepo)

From the monorepo root:

pnpm install
pnpm --filter @bragduck/cli build

Usage

Quick Start

1. Install Bragduck CLI globally:

   npm install -g @bragduck/cli

2. Authenticate with Bragduck:

   bragduck auth login

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

3. Connect your services (optional, for GitHub/GitLab/Bitbucket/Jira/Confluence):

   # GitHub: install and authenticate with GitHub CLI
   brew install gh && gh auth login
   
   # GitLab: authenticate with personal access token
   bragduck auth gitlab
   
   # Bitbucket: authenticate with API token
   bragduck auth bitbucket
   
   # Atlassian (Jira + Confluence): authenticate via OAuth
   bragduck auth atlassian

4. Sync your work items:

   bragduck sync

   Select services, review AI-refined brags, and create them.

5. View your brags:

   bragduck list

Commands

bragduck auth [subcommand]

Manage authentication for Bragduck and connected services.

# Login to Bragduck (default)
bragduck auth login

# Check authentication status for all services
bragduck auth status

# Authenticate with GitLab
bragduck auth gitlab

# Authenticate with Bitbucket
bragduck auth bitbucket

# Authenticate with Atlassian (Jira + Confluence)
bragduck auth atlassian

Subcommands:

• login - Authenticate with Bragduck (default if no subcommand)
• status - Show authentication status for all services
• bitbucket - Authenticate with Bitbucket using API token
• gitlab - Authenticate with GitLab using personal access token
• atlassian - Authenticate with Atlassian Cloud via OAuth 2.0

bragduck sync

Sync work items from authenticated services and create brags with AI-powered refinement.

# Interactive sync (choose services and items)
bragduck sync

# Sync last 7 days
bragduck sync --days 7

# Sync last 24 hours
bragduck sync --today

# Sync all services, skip prompts, auto-accept
bragduck sync --turbo

# Sync all authenticated services
bragduck sync --all

# Sync a specific source
bragduck sync --source github

Options:

• -d, --days <number> - Number of days to scan
• -t, --today - Scan the last 24 hours (shorthand for --days 1)
• --turbo - Skip all prompts, auto-select all items, auto-accept refinements
• -a, --all - Sync all authenticated services (skip service selection)
• -s, --source <type> - Explicit source type (github)

bragduck list

List your existing brags with filtering and pagination.

# List all brags (default: 50)
bragduck list

# Show 25 brags
bragduck list --limit 25

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

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

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

• Multi-Source Sync - GitHub, GitLab, Bitbucket, Jira, Confluence
• OAuth & Token Auth - Secure authentication per service
• AI-Powered Refinement - Transforms work items into professional achievements
• Interactive Selection - Checkbox interface for selecting items
• Rich Preview - Table preview of refined brags before creation
• Smart Filtering - Filter brags by tags and search keywords
• Turbo Mode - Fully automated sync with no prompts

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
• 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 | |-----|------|---------|-------------| | defaultCommitDays | number | 30 | Default days to scan (1-365) | | autoVersionCheck | boolean | true | Automatic version checking |

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 auth login

Problem: Service not showing in sync

Solution:

# Check which services are authenticated
bragduck auth status

GitHub CLI Not Authenticated

Problem: "Not authenticated with GitHub" error

Solution:

# Authenticate with GitHub CLI
gh auth login

# Verify authentication
gh auth status

No Work Items Found

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

Solution:

# Increase the scan days
bragduck sync --days 90

# Sync all authenticated services
bragduck sync --all

Enable Debug Mode

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

bragduck --debug <command>

Development

Prerequisites

• Node.js >= 18.0.0
• pnpm (workspace package manager)

Setup (monorepo)

# From the monorepo root
pnpm install

# Build the CLI
pnpm --filter @bragduck/cli build

# Run tests
pnpm --filter @bragduck/cli test

Project Structure

src/
├── commands/      # CLI commands
├── services/      # Business logic services
├── ui/            # Terminal UI components
├── types/         # TypeScript type definitions
├── utils/         # Utility functions
└── cli.ts         # CLI entry point

Scripts

| Script | Description | |--------|-------------| | pnpm --filter @bragduck/cli build | Build the project with tsup | | pnpm --filter @bragduck/cli dev | Build in watch mode for development | | pnpm --filter @bragduck/cli test | Run test suite | | pnpm --filter @bragduck/cli test:coverage | Run tests with coverage report | | pnpm --filter @bragduck/cli lint | Lint code with ESLint | | pnpm --filter @bragduck/cli lint:fix | Lint and auto-fix issues |

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.

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 (pnpm --filter @bragduck/cli test)
5. Commit your changes
6. Push to the branch
7. Open a Pull Request

License

MIT License - see LICENSE file for details

Made by Medhat Dawoud | Powered by AI