Brag CLI

A command-line tool for syncing your git commits to Bragbooq. Transform your development work into professional career achievements.

Features

• Zero-friction setup - Start syncing immediately, AI enhancement is optional
• Automatic syncing - Install a git hook to sync on every commit
• Smart amend detection - Automatically skips git commit --amend to avoid duplicates
• Raw or AI-enhanced commits - Works without an API key, or enhance commits with AI
• Multiple AI providers - OpenAI, Anthropic, or local Ollama
• Incremental sync - Only syncs new commits since last sync
• Local-first - Your code stays local, only commit metadata is synced

Installation

From npm (after package is published)

npm install -g @bragbooq/cli

Local Installation (for development)

# Clone the repo
git clone https://github.com/bragbooq/bragbooq.git
cd bragbooq/cli

# Install dependencies and build
npm install
npm run build

# Link globally to make 'brag' command available
npm link

This creates a symlink so the brag command works from anywhere on your machine.

Quick Start

# 1. Login to your Bragbooq account
brag login

# 2. Initialize in your git repository
brag init

# 3. Sync your commits
brag sync

# 4. (Recommended) Enable automatic syncing
brag install-hook

With the git hook installed, your commits will automatically sync to Bragbooq after each commit.

Commands

brag login

Authenticate with your Bragbooq account using browser-based OAuth.

brag logout

Sign out of your Bragbooq account.

brag init

Initialize brag in the current git repository.

brag init           # Interactive setup
brag init --skip-ai # Skip AI setup, sync raw commits only

brag sync

Sync your commits to Bragbooq.

brag sync                    # Sync recent commits
brag sync --limit 100        # Sync last 100 commits
brag sync --since 2024-01-01 # Sync commits since date
brag sync --branch main      # Sync specific branch
brag sync --raw              # Force raw sync (no AI)

brag config

View or update configuration.

brag config --list           # Show all settings
brag config --get aiProvider # Get specific value
brag config --ai-provider openai # Set up AI
brag config --remove-ai-key  # Remove AI config

brag status

Show brag status for the current repository.

brag install-hook

Install a git post-commit hook for automatic syncing.

brag install-hook    # Install the hook

After installation, every commit you make will automatically sync to Bragbooq in the background. This doesn't slow down your commit workflow - the sync happens asynchronously.

Note: Amended commits (git commit --amend) are automatically skipped to avoid duplicate brags.

brag uninstall-hook

Remove the automatic sync git hook.

brag uninstall-hook  # Remove the hook

brag hook-status

Check if the git hook is installed in the current repository.

brag hook-status     # Check hook status

AI Enhancement

AI enhancement transforms your commit messages into polished career achievements. It's completely optional - without AI, your commits sync as raw data, which Bragbooq can still display and organize.

Setting up AI

# During init
brag init  # Follow prompts

# Or later
brag config --ai-provider openai
brag config --ai-provider anthropic
brag config --ai-provider ollama

Supported Providers

Cost Estimates

• OpenAI gpt-4o-mini: ~$0.001 per commit
• Anthropic claude-3-5-haiku: ~$0.001 per commit
• Ollama: Free (local compute)

How It Works

1. Login: Authenticate with your Bragbooq account
2. Init: Register the repository for tracking
3. Sync: Parse local git history, optionally enhance with AI, send to Bragbooq

What gets synced?

For each commit, brag sends:

Raw data (always):

• Commit hash, message, author, date
• Branch name
• Files changed with line counts
• Repository name and remote URL

AI enhancement (if configured):

• Polished achievement title
• Impact-focused summary
• Identified technical skills
• Work category (feature, bugfix, etc.)

What stays local?

• Your source code
• Full commit diffs
• API keys (stored in OS keychain/config)

Configuration Files

Brag stores configuration in platform-specific locations:

• macOS: ~/Library/Preferences/brag-nodejs/
• Linux: ~/.config/brag-nodejs/
• Windows: %APPDATA%/brag-nodejs/

Environment Variables

Development

cd cli

# Install dependencies
npm install

# Build
npm run build

# Link globally (makes 'brag' command available)
npm link

# Or run directly without linking
node dist/index.js --help

# Watch mode for development
npm run dev

License

MIT