SciPaperlib

A local research library for collecting publications and retrieving inspectable, revision-bound evidence. No LLM, embedding service, or API key is required. Commands scipaperlib and spl are equivalent.

New user? Follow the quick start to turn a paper list or a shared library ZIP into a curated HTML table browser and Jupyter notebook.

Create, share, and use a library

Install SciPaperlib, create a named library, add papers, and download/index them:

python -m pip install scipaperlib
spl init --name research
spl add --name research 2409.11939
spl sync --name research

Rename it if needed, then prepare a ZIP snapshot:

spl --name research --rename-lib alice
spl bundle --name alice --out alice.spl.zip

Upload the ZIP to a file host of your choice and share its HTTPS download link. The snapshot includes saved papers, datasets, annotations, and indexes. A compatible, up-to-date snapshot is searchable immediately after import:

spl import-library --url https://example.org/alice.spl.zip --name my-alice
spl search --name my-alice --term "energy loss"

Omit --name to use the archive's name, falling back to the downloaded filename. If that name or location exists, interactive imports offer merge, separate copy, or cancel. Scripts must choose explicitly, for example --on-conflict separate creates alice-2, alice-3, etc. No existing library is silently overwritten. Local ZIPs use --file alice.spl.zip.

On a shared cluster, register the existing directory without copying its data:

spl --add-library /shared/project/alice --name cluster-alice --read-only
spl search --name cluster-alice --term "energy loss"
spl --list

Each user has their own registry. Read-only research caches stay in the user's cache directory. The owner prepares the shared library and its indexes.

See library relocation and sharing for moving a library, merging multiple libraries, resumable downloads, archive contents, and recovery. See all commands and switches or spl COMMAND --help for detailed options, and the guide for the full research workflow.

Named libraries initially live under ~/.scipaperlib/; set SCIPAPERLIB_DATADIR to choose another parent for new libraries. The registry is ~/.scipaperlib/config.json; SCIPAPERLIB_CONFIG overrides it. Registered locations remain stable when the data directory changes. Use --library PATH instead of --name for an explicit directory.

A fixed TUI activity panel shows progress and outcomes; CLI progress goes to stderr. The TUI prevents overlapping write operations and supports stopping imports after the current request.

Add papers from the TUI's paste area and remove a selected paper with confirmation. The CLI equivalent is spl remove PAPER_ID; removal archives files by default, while --delete-files permanently deletes them.

Textual, PDF extraction, and MCP are installed by default. Legacy pdf, mcp, and tui extras remain accepted for compatibility. See the guide for imports, provenance, recovery, and agent access.

Show the installed version with spl --version (or -v). Check for application updates with spl --check-upgrade; install an update with spl --upgrade, then restart SciPaperlib. Both accept --json and work through spl-tui without launching the TUI. Upgrades target the Python environment running the command; editable development installs are protected. This is separate from spl update, which updates papers.

Follow an INSPIRE author once through Add & Process → Followed authors → Resolve → Confirm & follow. Use Scan selected/Scan all authors or spl authors scan --all to add new publications without confirming again. Followed identities and scan history stay inside each library; unfollowing retains their papers.

For evidence-based Codex research across named libraries, use the read-only spl research-mcp endpoint and the bundled scipaperlib-research skill. See research setup and evaluation.

After installing scipaperlib, run spl --codex-setup (or spl setup-codex) to configure the research MCP connection and install its research, data-curation and data-visualization skills. All three skills ship inside the SciPaperlib package; no separate skill download or explorer package is required. Use spl --codex-setup --dry-run to preview; restart Codex after setup.

Undo managed Codex integration with spl setup-codex-remove (or --dry-run to preview). It preserves later user edits and retains backups; it never removes libraries.

CLI reports are human-readable by default. Use --json for scripts and agent CLI calls; MCP results remain structured. Browse annotations without a text query using spl papers --topic jets --tag review.

Snapshot import and library merging work offline after obtaining the archive; they never query publication providers.

Development: integrated paper/dataset acquisition, local provider-JSON queries and source-figure evidence are described in the guide.

Curate scientific data and generate a browser

Portable curation records describe exact quantities, units, conditions and source evidence. They are reusable across libraries containing the same paper and table revisions. Curation and browser commands read existing libraries without modifying them; interpretations live in a separate durable store.

python -m pip install 'scipaperlib[visualization]'
spl browse --name default --output ./browser --format both

This produces the existing three-panel offline HTML style plus a Jupyter notebook. Repeat --name to combine libraries. The figure starts blank; unreviewed and problematic records stay visible. Rebuilding uses saved reviews without calling an LLM. Numerical data are preserved, with explicit display conversions.

To have Codex resume curation and generate both outputs, simply ask:

Curate library research.

Or explicitly select the skill: Use $scipaperlib-data-curation on research. The skill handles source checks, saved progress, review reuse and visible issues; outputs default to ./research-browser. Say "no browser" for curation only, or "Rebuild the research browser" to render saved reviews without another review.

Curation follows each paper across libraries. spl bundle includes it in the same archive automatically. To adopt only curation for papers you already have:

spl import-library --file alice.spl.zip --name default --curation-only

This preserves paper files and memberships, reuses matching evidence, and reports skipped records and conflicts. No separate curation file is needed for sharing.

The curation and visualization guide documents the full paper-by-paper workflow, checkpoints, source identities, grouped decisions, transfer between libraries, conflict resolution, review scope, direct MCP/Python analysis, and the distinction between standalone HTML and notebook/plot exports. It also explains the transition from existing explorer workspaces.

Release automation

After bumping the package version and committing it, push a matching vX.Y.Z tag. The Release version tag workflow publishes a GitHub Release and explicitly dispatches Publish to PyPI for that tag. Publication follows the existing test, package-validation, and clean-install checks. No additional access token is needed.

For an existing tag, run Release version tag manually with its tag input. Publishing a GitHub Release manually also continues to trigger PyPI publication.