Installation

Installing buddy is easy. Simply pull it in via your package manager of choice, or download the binary directly.

Package Managers

Choose your package manager of choice:

::: code-group

npm install --save-dev @buddysh/buddy
# npm i -d @buddysh/buddy

# or, install globally via
npm i -g @buddysh/buddy

bun install --dev buddy
# bun add --dev @buddysh/buddy
# bun i -d buddy

# or, install globally via
bun add --global @buddysh/buddy

pnpm add --save-dev @buddysh/buddy
# pnpm i -d @buddysh/buddy

# or, install globally via
pnpm add --global @buddysh/buddy

yarn add --dev @buddysh/buddy
# yarn i -d buddy

# or, install globally via
yarn global add buddy

brew install buddy # coming soon

pkgx buddy # coming soon

:::

Prerequisites

Buddy requires:

• Bun - The fast package manager and runtime
• Node.js 18+ (for compatibility)
• Git - For repository operations

Install Bun

If you don't have Bun installed:

curl -fsSL https://bun.sh/install | bash

powershell -c "irm bun.sh/install.ps1 | iex"

npm install -g bun

Binaries

Choose the binary that matches your platform and architecture:

# Download the binary
curl -L https://github.com/stacksjs/buddy/releases/download/v0.9.1/buddy-darwin-arm64 -o buddy

# Make it executable
chmod +x buddy

# Move it to your PATH
mv buddy /usr/local/bin/buddy

# Download the binary
curl -L https://github.com/stacksjs/buddy/releases/download/v0.9.1/buddy-darwin-x64 -o buddy

# Make it executable
chmod +x buddy

# Move it to your PATH
mv buddy /usr/local/bin/buddy

# Download the binary
curl -L https://github.com/stacksjs/buddy/releases/download/v0.9.1/buddy-linux-arm64 -o buddy

# Make it executable
chmod +x buddy

# Move it to your PATH
mv buddy /usr/local/bin/buddy

# Download the binary
curl -L https://github.com/stacksjs/buddy/releases/download/v0.9.1/buddy-linux-x64 -o buddy

# Make it executable
chmod +x buddy

# Move it to your PATH
mv buddy /usr/local/bin/buddy

# Download the binary
curl -L https://github.com/stacksjs/buddy/releases/download/v0.9.1/buddy-windows-x64.exe -o buddy.exe

# Move it to your PATH (adjust the path as needed)
move buddy.exe C:\Windows\System32\buddy.exe

GitHub Setup

For GitHub Actions (Recommended)

When using buddy in GitHub Actions, you don't need a personal token. Just configure proper workflow permissions:

name: Dependency Updates
on:
  schedule:

    - cron: '0 2 * * 1'

jobs:
  update:
    runs-on: ubuntu-latest
    permissions:
      contents: write # Read repository and write changes
      pull-requests: write # Create and update pull requests
      actions: write # Update workflow files (optional)

    steps:

      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v1
      - run: bunx @buddysh/buddy update

        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Built-in token

The GITHUB_TOKEN is automatically provided by GitHub Actions with the permissions you specify.

For Local Development (Optional)

If you want to run buddy locally to create PRs, you'll need a personal access token:

Personal Access Token (Classic)

1. Go to GitHub Settings > Personal Access Tokens
2. Click "Generate new token (classic)"
3. Select scopes:
   • repo - Full repository access
   • workflow - Update GitHub Actions workflows (optional)
4. Set as environment variable:

export GITHUB_TOKEN=ghp*xxxxxxxxxxxxxxxxxxxx

Fine-grained Personal Access Token

1. Go to GitHub Settings > Personal Access Tokens (fine-grained)
2. Select repository access and grant permissions:
   • Contents: Read and Write
   • Pull requests: Write
   • Metadata: Read

Verification

Verify your installation:

# Check version
buddy --version

# Test GitHub authentication
buddy scan --verbose

# Generate sample configuration
buddy init

IDE Integration

VS Code

Install the Bun extension for better TypeScript support:

code --install-extension oven.bun-vscode

Configuration Files

Buddy will automatically detect and use:

• buddy.config.ts (TypeScript)
• buddy.config.js (JavaScript)
• buddy.config.json (JSON)

Docker Support

Run buddy in a container:

FROM oven/bun:latest

WORKDIR /app
COPY package.json bun.lockb ./
RUN bun install

COPY . .
RUN bun install -g buddy

CMD ["buddy", "scan"]

CI/CD Setup

GitHub Actions

name: Dependency Updates
on:
  schedule:

    - cron: '0 2 * * 1' # Weekly on Monday

jobs:
  update:
    runs-on: ubuntu-latest
    steps:

      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v1
      - run: bun install
      - run: bunx @buddysh/buddy update

        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

GitLab CI

dependency-updates:
  image: oven/bun:latest
  script:

    - bun install
    - bunx @buddysh/buddy update

  only:

    - schedules

  variables:
    GITLAB_TOKEN: $CI_JOB_TOKEN

Troubleshooting

Common Issues

Bun not found:

# Add Bun to PATH
echo 'export PATH="$HOME/.bun/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

GitHub token issues:

# Test token permissions
gh auth status
# or
curl -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/user

Package not found:

# Clear package cache
bun pm cache rm
# Reinstall
bun install

Getting Started

After installation, the fastest way to get started is with the interactive setup:

# Run interactive setup (recommended)
buddy setup

This comprehensive setup wizard will:

• 🔍 Detect your repository automatically from git remote
• 🔑 Guide token setup for Personal Access Tokens and repository secrets
• 🔧 Configure permissions for GitHub Actions
• ⚙️ Choose workflow presets optimized for your project type
• 📝 Generate configuration files and settings
• 🔄 Create workflows for automated dependency management
• 🎯 Provide next steps with clear instructions

Alternative: Manual Usage

If you prefer manual configuration, you can start with scanning:

# Scan for outdated dependencies
buddy scan

# Create dependency dashboard
buddy dashboard

# Update dependencies with pull requests
buddy update

Next Steps

• Complete Setup Guide - Detailed setup documentation
• Usage Examples - How to use buddy effectively
• Configuration - Customize buddy behavior
• CLI Reference - Complete command documentation