papis

name	papis
description	Academic bibliography manager Papis. Use this skill whenever the user wants to import an article, manage references, edit metadata, export to BibTeX, or perform any operation on a Papis library. Also triggers for: info.yaml, papis add/edit/export/list/update/tag, import from arXiv/DOI/BibTeX.
triggers	["/papis"]

Papis — Academic bibliography manager

Complete management of a Papis library: import, metadata editing, tags, BibTeX export.

Core principles

Library structure

A Papis library is a directory containing subfolders. Each valid document is a folder with an info.yaml file:

library/
├── graphical-metho-evans-2012/
│   ├── info.yaml
│   ├── graphical-metho-evans-2012.pdf
│   └── graphical-metho-evans-2012.md   # reading notes
└── another-paper-2024/
    ├── info.yaml
    └── another-paper-2024.pdf

Folder naming convention: lowercase with hyphens (e.g. graphical-metho-evans-2012).

info.yaml structure

author: Evans, Robin J.
title: Graphical Methods and Bayesian Networks
year: 2012
ref: Graphical_metho_Evans_2012       # BibTeX key (may differ from folder name)
files:
  - graphical-metho-evans-2012.pdf
notes: graphical-metho-evans-2012.md
abstract: |
  ...
tags: [bayesian, graphical-models]
doi: 10.xxxx/xxxxx
journal: Journal of Statistics
papis_id: <auto-generated>

Note: The ref field is the BibTeX key used in Quarto (@Graphical_metho_Evans_2012). The folder name is lowercase-hyphenated, but ref may use a different format (CamelCase or underscore).

---

Standard workflow: Import an article

Step 1 — Choose the library

papis list --libraries          # see available libraries
export PAPIS_LIB=library-name   # select the library
papis cache reset               # reset the cache

Step 2 — Import

From arXiv:

papis add --from arxiv https://arxiv.org/abs/1712.03134

From DOI:

papis add paper.pdf --from doi 10.1103/PhysRevLett.123.156401

Manually with metadata:

papis add paper.pdf \
    --folder-name graphical-metho-evans-2012 \
    --set author 'Evans, Robin J.' \
    --set title 'Graphical Methods and Bayesian Networks' \
    --set year 2012 \
    --set ref 'Graphical_metho_Evans_2012'

From a BibTeX file:

papis add --from bibtex references.bib

From clipboard BibTeX:

papis add --from bibtex "$(pbpaste)"   # macOS

Step 3 — Export to BibTeX (after import)

# Export to the active library directory
papis export --all --format bibtex > "$VAULT_DIR/Bibliography/references.bib"

---

Key commands

papis add — Add a document

papis add [OPTIONS] [FILES]...

Flag	Description
--from <source>	Source: arxiv, doi, bibtex, crossref
-s, --set KEY VALUE	Set a field (e.g. --set author "Smith")
--folder-name <name>	Folder name (convention: lowercase-hyphens)
--file-name <name>	Name of the copied PDF file
-d, --subfolder <path>	Subfolder within the library
--link	Symbolic link (no PDF copy)
--move	Move the PDF rather than copy
--edit	Open info.yaml for editing before adding
-b, --batch	Batch mode (no prompts)

papis list — List and search

papis list [OPTIONS] [QUERY]

Flag	Description
--all	Apply to all documents
--libraries	List libraries
--importers	List available importers
--exporters	List export formats
-f, --file	Show files
-d, --dir	Show directories
-i, --info	Show info.yaml path
--format '{doc[year]} {doc[title]}'	Custom format

Query syntax:

papis list author:einstein              # filter by field
papis list 'author:einstein year:1905'  # implicit AND
papis list --all                        # all documents

papis edit — Edit metadata or notes

papis edit [OPTIONS] [QUERY]
papis edit -n QUERY   # edit the notes file

papis update — Modify fields

papis update --set author "Einstein, Albert" "tags:classics"
papis update --append tags physics "year:2020"
papis update --remove tags physics QUERY
papis update --drop tags QUERY              # delete the field
papis update --auto "author:dyson"          # auto-fetch from sources

papis tag — Manage tags

papis tag --add TAG1 --add TAG2 QUERY
papis tag --remove TAG1 QUERY
papis tag --drop QUERY                  # remove all tags
papis tag --rename OLD NEW QUERY
papis tag --all --add TAG1 QUERY        # apply to all

papis export — Export

papis export --all --format bibtex > references.bib   # full library
papis export --all --out lib.bib                       # with --out flag
papis export 'author:einstein'                         # specific document
papis export --folder --out ./output QUERY             # export folder

papis cache — Manage the cache

papis cache clear    # clear the cache
papis cache reset    # clear and rebuild

---

Managing reading notes

The notes file is referenced in info.yaml:

notes: graphical-metho-evans-2012.md

papis edit -n QUERY    # open/create notes in the configured editor

---

_latex fields for BibTeX

For special TeX characters (&, $), create a field suffixed with _latex:

title: Mass & Energy
title_latex: Mass \& Energy

Papis will use title_latex when exporting to BibTeX.

---

Configuration (~/.config/papis/config)

[settings]
bibtex-unicode = False           # False = convert unicode to TeX
bibtex-ignore-keys = [abstract]  # exclude from BibTeX export

[my-library]
dir = /path/to/my/library
database-backend = sqlite        # papis | whoosh | sqlite

---

Expected behavior

1. Always verify the active library before any operation (papis list --libraries). Derive $VAULT_DIR (parent directory of the library folder) for vault operations.
2. Folder naming convention: <word1>-<word2>-<author>-<year> in lowercase.
3. The ref field is the BibTeX key — respect the existing format in the library (often Title_Author_Year or Author_Title_Year).
4. After any import, export to BibTeX: papis export --all --format bibtex > "$VAULT_DIR/Bibliography/references.bib".
5. Ask for confirmation before modifying or deleting documents.