Metadata-Version: 2.5
Name: paperstack-cli
Version: 0.3.1
Summary: Review, inspect, and retrieve research sources from one CLI
Project-URL: Repository, https://github.com/MilkClouds/paperstack
Project-URL: Issues, https://github.com/MilkClouds/paperstack/issues
License-File: LICENSE
Requires-Python: >=3.11.4
Requires-Dist: polars>=1.43
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: pyyaml>=6
Provides-Extra: pdf
Requires-Dist: pymupdf4llm>=0.0.17; extra == 'pdf'
Description-Content-Type: text/markdown

# 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`](examples/corpus/README.md); no assessment of real work is bundled with the package.

## Install

```bash
uv tool install paperstack-cli
```

PDF conversion is optional:

```bash
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.

```bash
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:

```bash
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

```bash
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](docs/ENTRIES.md).

## Inspect papers

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

```bash
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

```bash
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`:

```bash
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](docs/DBLP_RELEASES.md) for release maintenance.

## Configuration

| Variable | Purpose |
|---|---|
| `PAPERSTACK_DIR` | Explicit local corpus working tree |
| `PAPERSTACK_REPO` | Explicit GitHub corpus in `OWNER/REPO` form |
| `PAPERSTACK_TTL` | Remote corpus cache refresh interval; default `3600` seconds |
| `PAPERSTACK_PAPERS_DIR` | arXiv source and PDF cache |
| `SEMANTIC_SCHOLAR_API_KEY` | Optional higher-rate Semantic Scholar access |
| `OPENREVIEW_ACCESS_TOKEN` | Optional OpenReview access cookie value |
| `XDG_CONFIG_HOME` | Corpus profile configuration root |
| `XDG_CACHE_HOME` | Remote corpus and paper cache root |
| `XDG_DATA_HOME` | DBLP index root |

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

```bash
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.
