SciPaperlib

Version 0.1.4 includes human-readable CLI output and Codex research integration; see the guide for installation and usage.

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

The distribution and Python import name are scipaperlib. Commands scipaperlib and spl are equivalent; spl-tui launches spl --tui.

python -m pip install scipaperlib
scipaperlib demo ./demo-library
scipaperlib search --library ./demo-library --term mass --term "energy loss"
scipaperlib tui --library ./demo-library

Libraries are selected by name: spl-tui --name "heavy ion papers" uses a registered location, or creates ~/.scipaperlib/heavy_ion_papers_scipaperlib after confirmation. With no name, the library is default, stored initially at ~/.scipaperlib/default_scipaperlib. Set SCIPAPERLIB_DATADIR to change the parent directory for new libraries.

spl --list shows known libraries. Register an existing directory with spl --add-library /path/to/library --name "heavy ion papers". The registry lives at ~/.scipaperlib/config.json; SCIPAPERLIB_CONFIG overrides that file path. Registered locations remain stable when the data directory changes. Use --library PATH for an explicit location instead of --name. Scripts can pass --init-library to create a missing library without prompting.

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.

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.