beads/website/docs/cli-reference/sync.md
Amp a333dcaa75 fix(docs): purge stale bd sync/import/--branch refs + add CI doc validation (GH#2522)
Systematic cleanup of stale documentation references left over from the
Dolt migration:

- Replace all 'bd sync' → 'bd dolt push' / 'bd dolt pull' across 40+ files
- Replace all 'bd import' → 'bd init --from-jsonl' or remove
- Replace 'bd init --branch' → note about refs/dolt/data separation
- Fix AGENT_INSTRUCTIONS.md (highest impact: agents read this directly)
- Fix npm-package, claude-plugin, integrations, examples, website docs

Add scripts/check-doc-flags.sh to catch stale doc references:
- Checks for removed commands (bd sync, bd import)
- Checks for removed flags (bd init --branch)
- Warns on legacy SQLite/beads.db references
- Compares CLI_REFERENCE.md against bd help --all

Add CI job (check-doc-flags) and Makefile target (check-docs) to gate
PRs against doc freshness.

Prior art: feat/help-doc-generator branch has bd help --doc/--list for
generating docs FROM CLI output. This script validates docs AGAINST CLI
output — complementary approaches.

Amp-Thread-ID: https://ampcode.com/threads/T-019cde77-0722-7353-b63a-1779a5773ca6
Co-authored-by: Amp <amp@ampcode.com>
2026-03-11 13:25:40 -07:00

3.1 KiB

id title sidebar_position
sync Sync & Export 6

Sync & Export Commands

Commands for synchronizing with Dolt.

bd dolt push

Push changes to a Dolt remote.

bd dolt push [flags]

What it does:

  1. Dolt commit (snapshot current database state)
  2. Push commits to Dolt remote

Examples:

bd dolt push

When to use:

  • End of work session
  • Before switching machines
  • After significant changes

bd dolt pull

Pull changes from a Dolt remote.

bd dolt pull [flags]

What it does:

  1. Fetches commits from Dolt remote
  2. Merges into local database

Examples:

bd dolt pull

When to use:

  • Start of work session
  • After switching machines
  • Before creating new issues (to avoid duplicates)

bd export

Export database to JSONL format (for backup and migration).

bd export [flags]

Flags:

--output, -o    Output file (default: stdout)
--dry-run       Preview without writing
--json          JSON output

Examples:

bd export
bd export -o backup.jsonl
bd export --dry-run

When to use: bd export is for backup and data migration, not day-to-day sync. Dolt handles sync natively via bd dolt push/bd dolt pull.

bd migrate

Migrate database schema.

bd migrate [flags]

Flags:

--inspect    Show migration plan (for agents)
--dry-run    Preview without changes
--cleanup    Remove old files after migration
--yes        Skip confirmation
--json       JSON output

Examples:

bd migrate --inspect --json
bd migrate --dry-run
bd migrate
bd migrate --cleanup --yes

bd hooks

Manage git hooks.

bd hooks <subcommand> [flags]

Subcommands:

Command Description
install Install git hooks
uninstall Remove git hooks
status Check hook status

Examples:

bd hooks install
bd hooks status
bd hooks uninstall

Auto-Sync Behavior

With Dolt Server Mode (Default)

When the Dolt server is running, sync is handled automatically:

  • Dolt auto-commit tracks changes
  • Dolt-native replication handles remote sync

Start the Dolt server with bd dolt start.

Embedded Mode (No Server)

In CI/CD pipelines and ephemeral environments, no server is needed:

  • Changes written directly to the database
  • Must manually push to remote
bd create "CI-generated task"
bd dolt push  # Manual push needed

Conflict Resolution

Dolt handles conflict resolution at the database level using its built-in merge capabilities. When conflicts arise during bd dolt pull, Dolt identifies conflicting rows and allows resolution through SQL.

# Check for conflicts after pull
bd doctor --fix

Deletion Tracking

Deletions are tracked in the Dolt database:

# Delete issue
bd delete bd-42

# View deletions
bd deleted
bd deleted --since=30d

# Deletions propagate via Dolt push
bd dolt push

Best Practices

  1. Always push at session end - bd dolt push
  2. Always pull at session start - bd dolt pull
  3. Install git hooks - bd hooks install
  4. Check sync status - bd info shows sync state