bip-lit-import

name	bip-lit-import
description	Import Paperpile JSON export into bip library, rebuild database, and clean up.

Import Paperpile Library

Import a Paperpile JSON export from ~/Downloads/ into the bip reference library.

Usage

/bip-lit-import              # Auto-detect latest Paperpile JSON in ~/Downloads
/bip-lit-import ~/path.json  # Explicit file path

Workflow

1. Find the export file

If no path argument given, look for ~/Downloads/Paperpile*.json or ~/Downloads/*.json:

ls -lt ~/Downloads/Paperpile*.json 2>/dev/null || ls -lt ~/Downloads/*.json

If multiple files match, ask the user which one.

2. Dry-run import

Always dry-run first to show what will change:

bip import --format paperpile "<file>" --dry-run --human

Report the counts (new, updated, skipped, warnings) to the user. By default, entries missing required fields (title, author, published.year) are imported with sentinel placeholders ([no title], Unknown, year 0) and listed under warnings so they're not silently dropped — review the warning list and fix the affected Paperpile records when convenient. Entries with no useful metadata at all (no title, author, year, or DOI — typically Paperpile auto-stubs for unparsed web pages) are still skipped and counted under skipped. Pass --strict to revert to the old behavior of dropping any entry with a missing required field.

3. Import

bip import --format paperpile "<file>" --human

4. Rebuild database

bip rebuild --human

5. Delete the export file

rm "<file>"

6. Report

Summarize: new refs added, total count, file deleted. Notes from Paperpile are preserved and searchable via bip search.

7. Recommend cleanup if warnings fired

If the import reported a non-zero warnings count, recommend the cleanup query so the user can fix the upstream Paperpile records when convenient:

bip search --tag paperpile:incomplete

Every reference imported with a sentinel field ([no title], Unknown, year 0) is auto-tagged paperpile:incomplete. Once the user fixes the entry in Paperpile and re-imports, the next import replaces the stored reference and the tag disappears automatically, so the list shrinks until empty without any manual untagging step.