/import

description: Import issues and memories from JSONL
argument-hint: "[file|-] [--input file] [--dry-run] [--dedup] [--allow-stale]"

`bd import` imports newline-delimited JSON into an existing Beads database. Issues with new IDs are created and existing IDs use guarded upsert semantics. The command is not supported in proxied-server mode.

Usage

bd import                         # Read .beads/<import.path>
bd import backup.jsonl            # Read a specific file
bd import --input backup.jsonl    # Same as -i backup.jsonl
bd import -                       # Read JSONL from stdin
bd export --include-memories | bd import - # Round-trip issues and memories
bd import --dry-run backup.jsonl  # Parse and report without writing
bd import --json backup.jsonl     # Return a structured result

With no file argument, the source is the `import.path` file under `.beads/`; `import.path` defaults to `issues.jsonl`. Use either a positional file or `--input`/`-i`, not both. The special path `-` reads stdin. With `--global` and no file, the source is `global-issues.jsonl` in the active Beads directory.

Each non-empty line must be a JSON object. Issue records accept the schema emitted by `bd export`; `title` is the only required issue field. Records with `"_type":"memory"` and non-empty `key` and `value` fields are imported as persistent memories. Optional export header records are ignored, and tombstone rows are skipped. `bd export` omits memories by default; add `--include-memories` or `--all` when they should be carried into an import.

Merge and Safety Semantics

For records that supply `updated_at`, an incoming row rewrites an existing issue only when its timestamp is strictly newer. Older records are skipped wholesale, including their labels, comments, and dependencies. When timestamps are equal, the local issue row wins, while those auxiliary records still merge. The stale check is repeated inside the upsert so a concurrent newer local update is not overwritten.

If `updated_at` is omitted, the importer fills it with the current time during the write. A record naming an existing ID can therefore overwrite local state; include the exported timestamp when stale protection matters.

Use `--allow-stale` only when deliberately restoring an older snapshot: it disables that guard and can overwrite newer local issue state. Imports are upserts, and labels, comments, and dependencies are deduplicated. Re-running canonical export data or other input with stable issue IDs and preserved `updated_at` values is safe and converges. Without a preserved timestamp, each run can appear newer and rewrite the row. An issue record without an ID is assigned one; re-importing it can create another issue instead of targeting the first.

Large issue imports use bounded SQL transaction chunks. If one fails, the command exits nonzero and keeps the already committed prefix in the Dolt working set; no final import-summary Dolt commit is created. Re-run stable-ID input to resume only when its `updated_at` values are also preserved.

After a successful non-dry import with accepted issue or memory records, the command calls `store.Commit` with an import summary regardless of the `dolt.auto-commit` policy. That commit can include unrelated pending working-set changes; in direct server mode, config (including memories) is excluded from this commit. When commit isolation matters, run `bd doctor` before importing and proceed only when its Dolt Status check reports a clean working set.

The database must already exist; initialize or bootstrap it before importing. Use `--dry-run` to parse the input, apply optional title deduplication, and report issue and memory counts without writing. It does not run write-time field validation or predict stale skips and updates.

Flags

• `--input`, `-i <file>`: read a specific file instead of a positional path.
• `--dry-run`: report parsed record counts without writing.
• `--dedup`: skip an input issue whose title exactly matches, ignoring case, an

existing non-closed issue. Input rows are not compared with one another; if the existing-issue search fails, title filtering is skipped.

• `--allow-stale`: import older rows too, allowing newer local state to be

overwritten.

• `--json`: use global JSON-output mode for structured counts and IDs. The

`created` count is accepted issue rows, including existing rows, not only new inserts.