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.

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 setup-codex to configure the research MCP connection and install its bundled skill. Use --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.

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.