Papis: A Command-Line Document and Bibliography Manager

Papis as a Local Research Library

Papis addresses a specific problem: keeping documents, bibliographic records, notes, and related files together while making them searchable from a terminal. The README describes its users as people who want to add books and papers, search a library, import and export formats, synchronize with other software, and share documents without requiring a proprietary service. The interface is designed for researchers, developers, students, system administrators, and users who prefer command-line workflows, but the documented editor plugins and web app also provide entry points for less terminal-focused use.

The important design choice is storage. Papis stores each entry's bibliographic data in a human-readable `.yaml` file. That makes the record inspectable outside the application and suitable for editing by hand or through scripts. The library also stores attached documents. This local, file-oriented model differs from a service-centered reference manager: the README emphasizes sharing, synchronization, and interoperability, but it does not describe a hosted collaboration service or a required account.

Papis is not limited to PDF files. The quick tour demonstrates adding a downloaded manual and a paper, while the feature list refers broadly to books, papers, notes, and documents. The project topics also include bibliography formats, citation systems, DOI services, and integrations with tools such as Zotero and JabRef, although the repository excerpt does not document the behavior or setup of every integration. The supported feature set is broad, but the core value is simpler: a searchable collection whose records and files remain accessible through ordinary files.

CLI Storage, Metadata, and Document Flow

The documented workflow begins by placing documents in a location Papis can access and then adding them to the library. When the README adds a paper, the command identifies the file and supplies a DOI. Papis can then query metadata associated with that DOI and associate the resulting bibliographic entry with the document. This removes the need to type every field manually when an identifier is available.

For records without a useful DOI or for fields the provider did not return, `papis add` accepts `--set` assignments. The example supplies an author, title, year, and tag before confirmation. This indicates a hybrid model: automatic metadata retrieval is available, but users retain direct control over fields. The resulting YAML entry is the durable representation of the record, while the PDF or other attachment is the document itself.

Search and retrieval are built around the library rather than a separate database interface. The README lists author, title, tags, and other search fields, and provides commands for opening an attached file or editing an entry. Its picker can open, browse, or edit selected documents, with keyboard shortcuts configured through the `picktool` setting. The repository also includes an API intended for custom Python scripts, so automation can operate on the same document and metadata concepts exposed by the CLI.

Papis also includes TUIs and a web application. The web app is started with `papis serve` and is documented as listening at `http://localhost:8888`. The README presents this as a fallback when the CLI is inconvenient, such as on a tablet. The repository layout includes Python packages under `papis/`, tests, documentation, packaging files, and example scripts. That structure supports the claim that the application is extensible through code, but the excerpt does not provide a complete plugin API reference or a detailed description of every backend.

Installing Papis and Adding the First Documents

The README gives `pip` as the basic installation route. This installs the project into the active Python environment. The repository's `pyproject.toml` declares `papis` version 0.16.1, Python 3.10 or newer, and `GPL-3.0-or-later` as the project license text. The documentation also links to separate installation and configuration pages, which are the appropriate places to check for platform-specific instructions when the basic command is insufficient.

The following commands are copied from the README. They download two example documents into the current directory. A successful download should leave `libc.pdf` and `rnoti-p434.pdf` available for the subsequent add commands.

wget https://www.gnu.org/s/libc/manual/pdf/libc.pdf
wget https://www.ams.org/notices/201304/rnoti-p434.pdf

The DOI-backed add command associates the paper with metadata retrieved from the DOI. The expected result is a new library entry for `10.1090/noti963` that can be selected through later Papis commands.

papis add --from doi 10.1090/noti963 rnoti-p434.pdf

The second example shows how to set fields explicitly. `--confirm` makes the command request confirmation before committing the entry, while the repeated `--set` options populate individual metadata fields.

papis add libc.pdf --set author "Sandra Loosemore" \
                   --set title "GNU C reference manual" \
                   --set year 2018 \
                   --set tags programming \
                   --confirm

After creating entries, `papis open` opens an attached file and `papis edit` edits an entry. The README also documents command help, which is useful because the feature surface is wider than the short tour.

papis -h
papis add -h

BibTeX Import and Export Boundaries

Papis can read a BibTeX bibliography and export its library in the same general format. The README's import example uses `read`, names the input file, and includes `--all` so that the operation applies to all entries.

papis bibtex read mylib.bib import --all

The export example writes BibTeX to standard output. Redirecting that output creates a reusable bibliography file. The `--format bibtex` option makes the output format explicit.

papis export --all --format bibtex > mylib.bib

This interoperability is useful when a user wants to move between Papis and tools that understand BibTeX. It does not mean that every field, attachment, note, or picker-specific setting is guaranteed to survive a round trip. The excerpt does not document field mappings, conflict handling, duplicate detection, attachment handling during import, or rollback after an import. Those are real adoption questions for a library containing years of accumulated records.

The available documentation distinguishes the stable documentation for the latest released version from the documentation for the in-development version. That distinction matters for users following a migration or writing scripts against the API, because command behavior or extension points may differ between development and released documentation.

Editors, Pickers, Web Access, and Extensions

Papis is not limited to one interaction style. The README lists plugins for NeoVim and Emacs, a configurable picker, TUIs, and a web app. These options target different working contexts. A terminal picker can support rapid selection without requiring a browser, while editor integration can place metadata editing inside a text-oriented workflow. The web app provides a separate access route when the CLI is inconvenient.

The picker is controlled by the `picktool` configuration option. Its documented shortcuts include `Ctrl-o` to open a selected document, `Ctrl-b` to browse, and `Ctrl-e` to edit. These shortcuts are implementation details exposed by the project documentation, not universal keyboard conventions, so they should be checked against the selected picker before being incorporated into a workflow. The README also says that `F1` displays a complete list of available functionality from the picker.

The extension model is deliberately code-facing. The README describes a Python API for custom scripts, and the repository includes an `examples/scripts/` directory, a `papis/` package, tests, and documentation. This is useful for automation such as bulk transformations or custom retrieval workflows, but it also means adoption may involve reading the API documentation and maintaining scripts. The repository includes `HACKING.md` for code-related contribution information, while `CONTRIBUTING.md` describes contribution rules.

The web app is straightforward to start according to the README. Run `papis serve` and open `http://localhost:8888`. The excerpt does not specify authentication, deployment guidance, multi-user behavior, or production security settings, so the documented command should not be treated as a documented production deployment procedure.

Maintenance, Packaging, and GPL Constraints

The repository is not archived, and the last push was on 2026-10-03. Recent releases include v0.16.1 on 2026-09-13, v0.16.0 on 2026-08-18, and v0.15.0 on 2026-02-08. These dates indicate recent release activity in the repository history, although they do not by themselves guarantee compatibility for every plugin or script.

Packaging is based on Hatchling. The `pyproject.toml` build system requires `hatchling>=1.10.0`, names the package `papis`, and declares Python `>=3.10`. It also lists PyYAML and arXiv among its dependencies. The excerpt is truncated, so it is not possible to state the complete dependency set from the available project file.

The declared license is `GPL-3.0-or-later`, while the repository metadata identifies the project as GPL-3.0. That licensing choice is relevant to organizations distributing modified Papis code, bundling it with other software, or incorporating parts of it into a larger deployment. The license text should be reviewed for the intended distribution model. No legal conclusion about a particular deployment can be made from the project metadata alone.

The repository also contains a Dockerfile. It installs development tools, copies the repository into `/papis`, runs `tools/ci-install.sh`, and defines a command that runs linting and tests. That Dockerfile is oriented toward development and CI execution, not a documented production image. A separate `release.Dockerfile` is present, but its contents are not included in the available excerpt, so its behavior cannot be described further.

Where Papis Fits and Where It Does Not

Papis is a good fit for users who want their bibliography stored as readable YAML and their documents kept in a local library. It is also suited to people who prefer commands but need editor integration, a picker, a web interface, or scripted access. DOI lookup, explicit metadata editing, BibTeX import, and BibTeX export cover a practical core workflow.

It is the wrong choice for someone who needs a documented, turnkey collaboration service with hosted accounts and shared remote permissions. The README describes sharing and synchronization, but it does not specify a collaboration protocol, hosted account system, or deployment topology. A user who prioritizes a closed application ecosystem should verify those requirements before migrating.

It may also be a poor match for a user who wants a completely zero-configuration metadata database. Automatic DOI metadata retrieval depends on external metadata access, while manual fields require careful input. Large library conversions need attention because the documentation does not explain import conflict policy or round-trip guarantees. The local-file approach gives control, but the user becomes responsible for backups, file organization, and compatibility across machines.

Compared with a conventional graphical reference manager, Papis shifts more work toward command-line operation, file inspection, and scriptable customization. Compared with a plain directory of PDFs, it adds metadata, search, editing, import and export, and multiple interfaces. That is a meaningful difference for technical users, but the application also requires a workflow designed around records and files rather than a single opaque catalog.

Editorial conclusion

Adopt Papis if you want a local, file-based bibliography workflow with CLI access, metadata in YAML, and room for scripts or plugins. Do not choose it as a drop-in replacement for a service that requires hosted collaboration or a fixed proprietary interface without checking those requirements first. Verify Python version compatibility, your preferred metadata and attachment formats, editor and picker configuration, and the behavior of the web app at `http://localhost:8888` before migrating an existing library.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. papis/papis on GitHub
3. Project website
4. README
5. Releases