docs/SYNC_SETUP.md
Set up beads with Dolt sync so your issues follow you across computers.
You need two tools installed on every machine:
| Tool | Minimum Version | Install |
|---|---|---|
| bd (beads CLI) | 0.59.0+ | See INSTALLING.md |
| Dolt | 1.81.8+ | brew install dolt or dolt install script |
Verify both are installed:
bd version # must be 0.59.0+
dolt version # must be 1.81.8+
cd your-project
bd init
This creates the .beads/ directory with a Dolt database and starts a background dolt sql-server.
bd create "Set up CI pipeline" -p 1 -t task
bd create "Add authentication" -p 2 -t feature
bd list
Point beads at your Git remote for sync. Dolt stores data under refs/dolt/data, separate from your normal Git refs — so you can use the same remote as your source code.
# GitHub (SSH — recommended)
bd dolt remote add origin git+ssh://[email protected]/org/repo.git
# GitHub (HTTPS)
bd dolt remote add origin https://github.com/org/repo.git
# Other options: DoltHub, S3, GCS, local path
# See DOLT-BACKEND.md for all remote types
bd dolt push
Verify the push worked:
git ls-remote origin | grep dolt
# Expected: <hash> refs/dolt/data
When you clone a repo that already has beads data on the remote, a standard git clone does not fetch refs/dolt/data. You need to bootstrap the Dolt database.
On recent versions of bd, bd bootstrap handles everything automatically:
git clone [email protected]:org/repo.git
cd repo
bd bootstrap
bd bootstrap auto-detects refs/dolt/data on origin, clones the Dolt database, and configures the remote. Verify with:
bd list # should show your issues
bd vc log # should show commit history
If bd bootstrap succeeds, you're done — skip to Day-to-day Sync.
If bd bootstrap doesn't work (older bd versions, unusual remote configs), follow these steps:
Step 1: Confirm the remote has beads data
git ls-remote origin | grep dolt
# Expected: <hash> refs/dolt/data
# If missing, the remote has no beads data — use bd init normally.
Step 2: Initialize beads
bd init
This creates .beads/ with an empty database. Ignore any warnings about bd bootstrap — we'll replace the empty database manually.
Step 3: Stop the Dolt server
bd dolt stop
Step 4: Find your database name and remove the empty database
# Check your database name
cat .beads/metadata.json # look for "dolt_database"
The dolt_database field is your <dbname> (typically the repo name).
# Remove the empty database
rm -rf .beads/dolt/<dbname>/
Step 5: Clone the Dolt data from the remote
cd .beads/dolt
dolt clone [email protected]:org/repo.git <dbname>
cd ../..
Step 6: Start the server and migrate
bd dolt start
bd migrate --yes
Step 7: Ensure the remote is registered
bd dolt remote add origin git+ssh://[email protected]/org/repo.git
If you see "remote already exists", that's fine — dolt clone already set it up.
Step 8: Verify
bd dolt remote list # should show origin
bd list # should show your issues
Once set up on both machines, sync is two commands:
# Push your changes to the remote
bd dolt push
# Pull changes from the remote
bd dolt pull
Machine A Machine B
───────── ─────────
bd create "New task" -p 1
bd dolt push
bd dolt pull
bd update bd-a1b2 --claim
bd close bd-a1b2 --reason "Done"
bd dolt push
bd dolt pull
bd list # sees the closed task
bd dolt ... commands — never run raw dolt CLI commands while the Dolt server is running. It causes journal corruption.bd dolt pull will fail with "cannot merge with uncommitted changes". Run bd dolt commit first.A stale refs/dolt/data from a previous database is conflicting. Clear it and retry:
git update-ref -d refs/dolt/data
bd dolt push
Commit your working set first:
bd dolt commit
bd dolt pull
This was a bug in bd < 0.59.0. Upgrade bd:
brew upgrade beads
# or re-run the install script
The Dolt database wasn't bootstrapped. Either run bd bootstrap or follow the manual path above.
bd doctor --fix --yes
WARNING: Do NOT manually remove files inside .dolt/ directories (including
noms/LOCK). These are Dolt-internal files and removing them will cause
unrecoverable data corruption. Dolt manages these files itself.
The Dolt server's working directory no longer exists (common after branch switches). Restart it:
bd dolt stop
bd dolt start
This guide was inspired by @leonletto's community setup guide at leonletto.github.io/thrum, which documented the end-to-end setup and sync process including the manual bootstrap workflow. Thanks for contributing to the beads community!