Moving Forge kernel issue data across a boundary: project the backlog to a git-committable snapshot (and hydrate it back), or import an existing issue store into the kernel. This is data portability — distinct from schema/database migrations and from the cloud backend sync (forge sync).
forge export # write the kernel backlog to git-tracked JSONL (deterministic)
forge export --dir <path> # choose the projection directory
forge export --dry-run # show what would be written, change nothing
forge export --import # read the committed JSONL snapshot back INTO the kernel (hydrate)
forge export is the D16 portability projection: a deterministic, git-committable snapshot of the backlog you can review in a diff and carry between machines or checkouts. forge export --import is the reverse — it hydrates the kernel from that on-disk snapshot; a re-import that finds everything already present reports "already hydrated" rather than claiming it imported anything.
forge migrate --from beads [--dry-run] # import a Beads issue store into the kernel
forge migrate --from beads --source <dir> # point at exported beads *.jsonl (defaults to auto-detecting .beads/)
forge migrate --dry-run # preview the v2→v3 migration (the ONLY supported mode without --from)
forge migrate --from beads is the onboarding path for users coming from Beads — it imports a Beads issue store into the Forge Kernel (--dry-run reads + maps only, writing nothing). Without --from, migrate is v2→v3 preview only: --dry-run is required and applying the migration is not yet available.
Boundaries
- The cloud/backend sync of the kernel is
forge sync(cloud-native) — a different operation; this skill is the local, git-based portability projection. - A database/schema migration (adding a column, altering a table) is application work — that's plan/dev, not
forge migrate. - Persisting a decision or note is memory (
forge remember), not export. - Syncing a git branch with main before a PR is ship/worktree.