beads/website/docs/cli-reference/sync.md

id, title, sidebar_position

id	title	sidebar_position
sync	Sync & Export	6

Sync & Export Commands

Commands for synchronizing with git.

bd sync

Full sync cycle: export, commit, push.

bd sync [flags]

What it does:

1. Exports database to .beads/issues.jsonl
2. Stages the JSONL file
3. Commits with auto-generated message
4. Pushes 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.

bd export [flags]

Flags:

--output, -o    Output file (default: .beads/issues.jsonl)
--dry-run       Preview without writing
--json          JSON output

Examples:

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

bd import

Import from JSONL file.

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 .beads/issues.jsonl
bd import -i backup.jsonl --dry-run
bd import -i issues.jsonl --orphan-handling resurrect
bd import -i issues.jsonl --dedupe-after --json

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 Daemon (Default)

The daemon handles sync automatically:

• Exports to JSONL after changes (5s debounce)
• Imports from JSONL when newer

Without Daemon

Use --no-daemon flag:

• Changes only written to SQLite
• Must manually export/sync

bd --no-daemon create "Task"
bd export  # Manual export needed

Conflict Resolution

Merge Driver (Recommended)

Install the beads merge driver:

bd init  # Prompts for merge driver setup

The driver automatically:

• Merges non-conflicting changes
• Preserves both sides for real conflicts
• Uses latest timestamp for same-issue edits

Manual Resolution

# After merge conflict
git checkout --ours .beads/issues.jsonl
bd import -i .beads/issues.jsonl
bd sync

Deletion Tracking

Deletions sync via .beads/deletions.jsonl:

# Delete issue
bd delete bd-42

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

# Deletions propagate via git
git pull  # Imports deletions from remote

Best Practices

1. Always sync at session end - bd sync
2. Install git hooks - bd hooks install
3. Use merge driver - Avoids manual conflict resolution
4. Check sync status - bd info shows daemon/sync state