beads/website/docs/cli-reference/sync.md
beads/crew/elinor 90da8f6028 docs: remove stale JSONL references from ~73 markdown files (bd-9ni.4)
Replace JSONL storage/sync references with Dolt-native equivalents across
documentation, plugin resources, website docs, agent instructions, and
example READMEs. Preserves legitimate JSONL references (bd import/export
commands, CHANGELOG history, routes.jsonl/interactions.jsonl concepts).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-22 22:18:02 -08:00

3.8 KiB

id title sidebar_position
sync Sync & Export 6

Sync & Export Commands

Commands for synchronizing with Dolt.

bd sync

Full sync cycle: Dolt commit and push.

bd sync [flags]

What it does:

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

Flags:

--json     JSON output
--dry-run  Preview without changes

Examples:

bd sync
bd sync --json

When to use:

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

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 import

Import from JSONL file (for migration and recovery).

bd import -i <file> [flags]

Flags:

--input, -i           Input file (required)
--dry-run             Preview without changes
--orphan-handling     How to handle missing parents
--dedupe-after        Run duplicate detection after import
--json                JSON output

Orphan handling modes:

Mode Behavior
allow Import orphans without validation (default)
resurrect Restore deleted parents as tombstones
skip Skip orphaned children with warning
strict Fail if parent missing

Examples:

bd import -i backup.jsonl
bd import -i backup.jsonl --dry-run
bd import -i issues.jsonl --orphan-handling resurrect
bd import -i issues.jsonl --dedupe-after --json

When to use: bd import is for loading data from external JSONL files or migrating from a legacy setup. For day-to-day sync, use 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 sync
bd create "CI-generated task"
bd sync  # Manual sync needed

Conflict Resolution

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

# Check for conflicts after sync
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 sync
bd sync

Best Practices

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