Paperstack

Paperstack is an open-source CLI for maintaining, querying, and publishing an independently authored research corpus. The software and corpus are separate: Paperstack can be public while each corpus and its editorial judgments remain under its maintainer's control.

It can search typed reviews, initialize and validate entries, inspect external paper metadata, read arXiv sources, manage a selected-venue DBLP index, and build a static viewer. A synthetic corpus lives in examples/corpus; no assessment of real work is bundled with the package.

Install

uv tool install paperstack-cli

PDF conversion is optional:

uv tool install 'paperstack-cli[pdf]'

Choose a corpus

Register either a local working tree or a GitHub repository. The first registered corpus becomes active.

paperstack corpus add work --path ~/research/reviews
paperstack corpus add private --repo OWNER/private-reviews
paperstack corpus list
paperstack corpus use private
paperstack corpus remove work

Private GitHub repositories use the existing gh login without storing its token:

gh auth login
paperstack review sync

PAPERSTACK_DIR and PAPERSTACK_REPO remain available for automation. Explicit environment variables take priority, then a surrounding corpus working tree, then the active profile. Profiles are stored in ${XDG_CONFIG_HOME:-~/.config}/paperstack/config.json.

Review corpus

paperstack review show example2026paperstack --brief
paperstack review show arxiv:2410.24164 --json
paperstack review list --quality good --tag vla
paperstack review search "flow matching"
paperstack review init <key> --id arxiv:NNNN.NNNNN --title "Verbatim title" --editor <name>
paperstack review check --style
paperstack review audit
paperstack review citations --fetch

Paper entries, talks, and posts use separate contracts under entries/{papers,talks,posts}/. The complete schemas, writing guide, and source-reading workflow are in Entry authoring.

Inspect papers

These commands use external source records and do not select a citation or make an editorial judgment:

paperstack paper search "Attention Is All You Need" --source dblp
paperstack paper metadata arxiv:2106.09685
paperstack paper metadata doi:10.1109/CVPR.2016.90 --source crossref
paperstack paper read arxiv:2604.23073 --outline
paperstack paper read arxiv:2604.23073 --section 6
paperstack paper pdf arxiv:2602.09017

metadata accepts arxiv:, doi:, dblp:, and openreview: references. read and pdf require an arxiv: reference. Structured commands expose scoped --json flags; networked commands expose scoped --offline flags.

Build a viewer

paperstack viewer build
paperstack viewer serve --port 8000

The viewer is generated from the selected corpus. Source Markdown remains available alongside the rendered pages.

DBLP index

The optional selected-venue index accelerates DBLP search and is required by review audit:

paperstack index dblp status
paperstack index dblp install
paperstack index dblp update

Installed snapshots are content-addressed and verified by SHA-256, schema, and embedded metadata before an atomic pointer switch. See DBLP snapshot releases for release maintenance.

Configuration

The console entry point also loads the nearest .env without overriding exported variables. Review exit codes are 0 for hits, 1 for no match, 2 for ambiguity, and 3 for unavailable data or invalid configuration.

Development

uv run --group lint ruff check .
uv run --group lint ruff format --check .
uv run --group test pytest -q
PAPERSTACK_DIR=examples/corpus uv run paperstack viewer build --output /tmp/paperstack-site

Paperstack is licensed under Apache-2.0. Corpora are separate works and may use their own terms.