papers

Command-line tool to manage your bibliography (PDFs + BibTeX).

papers keeps a BibTeX file for each of your projects, and the PDFs that go with it. Give it a PDF: it reads the DOI, fetches the entry from crossref, renames the PDF after the entry and adds both to your project. A project can use another library as its pool, and take its entries and PDFs from there, so that each PDF is stored and fetched once.

It works like git: one papers command with subcommands, run inside a project folder.

• Add papers from PDFs, DOIs, bibtex, RIS, CSL-JSON or BibJSON files, or whole folders. The DOI is read from the PDF, and the metadata comes from crossref (by DOI or full-text search), doi.org, google scholar or OpenAlex.
• Name the PDFs with a template ({authorX}_{year}_{title} by default), and attach supplements to an entry.
• Share entries and PDFs between projects: a shallow project uses another library as its pool, takes its entries from there and links to its PDFs; any library can also exchange entries with another one (--pool PATH). papers pull, push and sync exchange the entries with a field-by-field three-way merge; each project keeps its own keys.
• Search and act on a library with papers list (tag, edit, delete, rename, fetch, deduplicate), in the style of find and grep.
• Detect duplicates by DOI, arXiv identifier, ISBN, or authors and title, and merge them.
• Export a selection as a library with copies of its PDFs, or as RIS and CSL-JSON (for Zotero, EndNote, pandoc) or BibJSON (for programs).
• Plain files: the bibtex is the database, the PDFs stay in folders you see, and the library can be edited with any tool.
• Undo anything: every command is a step of the library's history, kept on your computer; papers undo / papers redo take back any command, with the files it moved, renamed or deleted, and a change made outside papers is never lost.
• Fast on large libraries: the parsed bibtex is cached piece by piece, and papers status compares a project with its pool only where they changed.

Get started

pip install --pre papers-cli    # the 3.0 beta
cd ~/projects/my-paper
papers init                     # a library: papers.bib and files/ here
papers add ~/Downloads/paper.pdf
papers list

• Installation — pip install and external dependencies.
• Quickstart — a self-contained project, and a shallow project that uses it as pool.
• Upgrading from papers 2 — what becomes of a papers 2 library, and papers migrate.
• Adding entries — from PDFs, DOIs, bibtex, or whole directories.
• Configuration — libraries, settings and pools.

Guides

• Adding entries
• Listing and searching
• Renaming files and keys
• Files
• Configuration
• Pools
• Shallow libraries
• Export
• A global shared library
• Managing your library
• Using git
• Undo and redo

From the same author

A few other open-source tools I maintain.

Scientific writing & data

• texmark — write scientific articles in Markdown and convert them to journal-ready LaTeX/PDF.
• datamanifest — declarative, reproducible dataset management. (See also the datamanifest.toml format spec and the DataManifest.jl Julia port.)

Speech to Text (dictate) and Text to Speech (read-aloud) tools

• scribe — speech-to-text dictation.
• bard — text-to-speech reader.