| 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
/bip-lit-import ~/path.json
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.