beads/website/docs/getting-started/upgrading.md
matt wilkie c86acb0d73
Retire legacy Homebrew tap publishing (#4478)
* Retire legacy Homebrew tap publishing

Stop the release workflow from publishing the independent bd tap formula, and document Homebrew core beads as the supported Homebrew package with migration commands for legacy tap users.

Agent-Signature: codex-gpt-5.5-medium on behalf of matt wilkie

* Sync beads-mcp uv.lock with pyproject version

CI Package Gate (MCP) fails on `uv sync --all-groups --locked` because
integrations/beads-mcp/uv.lock still pins the editable package at 1.0.5
while pyproject.toml declares 1.1.0-rc.1. This drift exists on
upstream/main itself, not from this branch (PR #4478 only retires the
legacy Homebrew tap and touches no MCP package files), so the branch is
already on top of the latest upstream/main and a rebase cannot resolve it.

Regenerate the lockfile with `uv lock`. The only change is the package's
own version (1.0.5 -> 1.1.0rc1); no dependency versions change.

Agent-Signature: claude-opus-4-8-high on behalf of matt wilkie
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-22 19:26:46 -07:00

6 KiB
Raw Blame History

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

Use the command that matches your install method.

Install method Platforms Command
Quick install script macOS, Linux, FreeBSD curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
PowerShell installer Windows irm https://raw.githubusercontent.com/gastownhall/beads/main/install.ps1 | iex
Homebrew macOS, Linux brew upgrade beads
go install (server-mode only) macOS, Linux, FreeBSD, Windows CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest
go install (embedded-capable) macOS, Linux, Windows CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest
npm macOS, Linux, Windows npm update -g @beads/bd
bun macOS, Linux, Windows bun install -g --trust @beads/bd
From source (Unix shell) macOS, Linux, FreeBSD git pull && make build

Quick install script (macOS/Linux/FreeBSD)

curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash

PowerShell installer (Windows)

irm https://raw.githubusercontent.com/gastownhall/beads/main/install.ps1 | iex

Homebrew

brew upgrade beads

If you still have the old tap formula installed as bd, switch to the Homebrew core formula:

brew uninstall bd
brew untap gastownhall/beads 2>/dev/null || true
brew untap steveyegge/beads 2>/dev/null || true
brew install beads

go install

# Server-mode only
CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest

# Embedded-capable
CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest

From Source

cd beads
git pull
make build
sudo mv bd /usr/local/bin/

After Upgrading

Important: After upgrading, update your hooks:

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

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

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

# 4. If using Dolt backend, restart the server
bd dolt stop && bd dolt start

Why update hooks? Git hooks are versioned with bd. Outdated hooks may miss export refresh, legacy fallback, or safety 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

Cross-era Upgrades

If you're upgrading from a much older version of bd, your project may use a different storage backend. bd has gone through several storage eras:

Era Versions Storage
SQLite v0.30–v0.50 .beads/beads.db
Dolt server v0.50–v0.58 .beads/dolt/ (external server)
Embedded Dolt (old) v0.59–v0.63.2 .beads/dolt/ (in-process)
Embedded Dolt (current) v0.63.3+ .beads/embeddeddolt/

From v0.63.3+ (current era)

Upgrade the binary and run:

bd migrate

If the project was initialized before bd init automatically wired git origin as the Dolt remote, verify the remote after upgrading:

bd dolt remote list

When the list is empty, fix it on the machine whose local database is authoritative:

bd export -o .beads/issues.pre-remote.jsonl   # optional issue audit export
bd dolt remote add origin git+ssh://git@github.com/org/repo.git
bd dolt push

Commit the resulting .beads/config.yaml change so other clones can run bd bootstrap or bd dolt pull.

From v0.59–v0.63.2 (old embedded)

Direct upgrade works automatically:

# Just use the new binary — it handles the conversion
bd list

From v0.50–v0.58 (Dolt server era)

The old binary used an external Dolt SQL server. The new binary uses an embedded engine.

# 1. Export your data while the old binary still works
bd list --json -n 0 --all > .beads/issues.jsonl

# 2. Stop the Dolt server
dolt sql-server --stop  # or kill the process

# 3. Remove stale server metadata and old storage directories
rm -f .beads/metadata.json .beads/config.json
rm -rf .beads/dolt .beads/embeddeddolt

# 4. Initialize with the new binary
bd init --from-jsonl --quiet

# 5. Verify
bd list --all

From v0.30–v0.50 (SQLite era)

The old binary stored data in SQLite. The new binary uses Dolt.

Recommended: use the migration script (requires sqlite3 and jq):

# Download the script from the beads repo
curl -fsSLO https://raw.githubusercontent.com/gastownhall/beads/main/scripts/migrate-sqlite-to-current.sh
chmod +x migrate-sqlite-to-current.sh

# Run it in your project directory
./migrate-sqlite-to-current.sh

The script exports issues, dependencies, and labels from SQLite, handles type normalization, and imports everything into the new Dolt backend.

Alternative: manual export with the old binary. Old binaries are always available on GitHub Releases. Download the version that matches your project, then:

# 1. Export with the old binary
./bd-old list --json -n 0 --all > .beads/issues.jsonl

# 2. Import with the current binary
bd init --from-jsonl --quiet

# 3. Verify
bd list --all

Note: The manual export preserves issue content but not dependencies or labels. Use the migration script for a more complete transfer.

Troubleshooting Upgrades

Hooks out of date

bd hooks install

Database schema changed

bd migrate --dry-run
bd migrate

Recovery after upgrade

If you need to restore from a backup:

bd init
bd backup restore [path] --force

Or pull from a Dolt remote:

bd dolt pull