beads/website/docs/getting-started/upgrading.md
Pablo LION a46c1db86e fix: correct brew commands and remove dead homebrew CI job
The Homebrew formula is named "beads" (not "bd"), so all brew commands
must use `brew install beads` / `brew upgrade beads`. Also removes the
dead update-homebrew job from release.yml — homebrew-core handles
formula updates automatically.

Follows up on #1557 which fixed the Go code in bd doctor.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-09 08:02:42 +01:00

1.9 KiB

id title sidebar_position
upgrading Upgrading 4

Upgrading bd

How to upgrade bd and keep your projects in sync.

Checking for Updates

# Current version
bd version

# What's new in recent versions
bd info --whats-new
bd info --whats-new --json  # Machine-readable

Upgrading

Homebrew

brew upgrade beads

go install

go install github.com/steveyegge/beads/cmd/bd@latest

From Source

cd beads
git pull
go build -o bd ./cmd/bd
sudo mv bd /usr/local/bin/

After Upgrading

Important: After upgrading, update your hooks and restart daemons:

# 1. Check what changed
bd info --whats-new

# 2. Update git hooks to match new version
bd hooks install

# 3. Restart all daemons
bd daemons killall

# 4. Check for any outdated hooks
bd info  # Shows warnings if hooks are outdated

Why update hooks? Git hooks are versioned with bd. Outdated hooks may miss new auto-sync features or bug fixes.

Database Migrations

After major upgrades, check for database migrations:

# Inspect migration plan (AI agents)
bd migrate --inspect --json

# Preview migration changes
bd migrate --dry-run

# Apply migrations
bd migrate

# Migrate and clean up old files
bd migrate --cleanup --yes

Daemon Version Mismatches

If you see daemon version mismatch warnings:

# List all running daemons
bd daemons list --json

# Check for version mismatches
bd daemons health --json

# Restart all daemons with new version
bd daemons killall --json

Troubleshooting Upgrades

Old daemon still running

bd daemons killall

Hooks out of date

bd hooks install

Database schema changed

bd migrate --dry-run
bd migrate

Import errors after upgrade

Check the import configuration:

bd config get import.orphan_handling
bd import -i .beads/issues.jsonl --orphan-handling allow