Metadata-Version: 2.5
Name: arxiv-subscription-viewer
Version: 0.4.0
Summary: Review arXiv papers from your terminal with live search, local notes, and citation exports
Project-URL: Homepage, https://nicolasschuler.github.io/arxiv-subscription-viewer/
Project-URL: Documentation, https://nicolasschuler.github.io/arxiv-subscription-viewer/
Project-URL: Repository, https://github.com/NicolasSchuler/arxiv-subscription-viewer
Project-URL: Issues, https://github.com/NicolasSchuler/arxiv-subscription-viewer/issues
Project-URL: Changelog, https://github.com/NicolasSchuler/arxiv-subscription-viewer/blob/main/CHANGELOG.md
Author-email: Nicolas Sebastian Schuler <nicolas.schuler@kit.edu>
License-Expression: MIT
License-File: LICENSE
Keywords: academic,arxiv,papers,research,terminal,textual,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Terminals
Classifier: Typing :: Typed
Requires-Python: >=3.13
Requires-Dist: defusedxml>=0.7.1
Requires-Dist: httpx>=0.27.0
Requires-Dist: pillow>=12.0.0
Requires-Dist: platformdirs>=3.0
Requires-Dist: pypdf>=6.16.1
Requires-Dist: pypdfium2>=5.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0.0
Requires-Dist: textual>=7.3.0
Provides-Extra: fuzzy
Requires-Dist: rapidfuzz>=3.0.0; extra == 'fuzzy'
Provides-Extra: ml
Requires-Dist: joblib>=1.4; extra == 'ml'
Requires-Dist: scikit-learn<2,>=1.7; extra == 'ml'
Provides-Extra: semantic-fastembed
Requires-Dist: fastembed>=0.8.0; extra == 'semantic-fastembed'
Description-Content-Type: text/markdown

# arXiv Subscription Viewer

**Review arXiv papers from your terminal. Keep a reading queue you can return to.**

For researchers who follow a field or work through a literature search: scan abstracts, star promising papers, add notes, and export citations. Start with live arXiv search or browse saved subscription emails. Your review state stays on your machine; AI services are optional.

![arXiv Subscription Viewer showing a paper list beside the selected abstract, with search, selection, and export shortcuts](https://raw.githubusercontent.com/NicolasSchuler/arxiv-subscription-viewer/main/docs/screenshot_preview.png)

*Application capture from the development checkout, using fictional paper fixtures. The released interface may differ.*

[Website](https://nicolasschuler.github.io/arxiv-subscription-viewer/) · [Guides](https://github.com/NicolasSchuler/arxiv-subscription-viewer/blob/main/docs/README.md) · [PyPI](https://pypi.org/project/arxiv-subscription-viewer/) · [Changelog](https://github.com/NicolasSchuler/arxiv-subscription-viewer/blob/main/CHANGELOG.md)

<a id="-getting-started"></a>

## Getting started

### Install

Use [uv](https://docs.astral.sh/uv/getting-started/installation/) to install the published package in an isolated tool environment. The application requires Python 3.13+; this command lets uv provision Python 3.13 if needed.

```bash
uv tool install --python 3.13 arxiv-subscription-viewer
```

### First run

Open a terminal and load a small page of recent papers in artificial intelligence:

```bash
arxiv-viewer search --category cs.AI --mode page --max-results 20
```

Dismiss the first-run welcome with `Enter`. You should see up to 20 papers and the selected paper's details. This uses the arXiv API and needs an internet connection, but no account, API key, or local files. Replace `cs.AI` with your category. Omitting `--mode page` collects the newest matching submission day, which can take longer.

Already saving arXiv emails? Open `arxiv-viewer browse` from the directory containing your populated `history/` folder. The [history guide](https://github.com/NicolasSchuler/arxiv-subscription-viewer/blob/main/docs/history-mode.md) includes a complete input example.

If the command is missing or results do not load, follow [first-run troubleshooting](https://github.com/NicolasSchuler/arxiv-subscription-viewer/blob/main/docs/troubleshooting.md#first-run-recovery). `arxiv-viewer doctor` diagnoses your setup; warnings about optional features are not prerequisites for live search.

<details>
<summary>Install with pip instead</summary>

With Python 3.13+ installed, create and activate a virtual environment:

```bash
python3.13 -m venv .venv
source .venv/bin/activate
python -m pip install arxiv-subscription-viewer
```

On Windows, use `py -3.13 -m venv .venv`, then `.venv\Scripts\Activate.ps1` in PowerShell. Run the same first-run command above.

</details>

### Typical flow

1. **Scan.** Move with `j` / `k` or the arrow keys. Read the selected abstract in the details pane.
2. **Keep what matters.** Press `x` to star a paper, `n` to add a note, and `r` to mark it read.
3. **Narrow the list.** Press `/` and enter `starred` or `unread`. This filters the papers already loaded; `A` starts a new arXiv search.
4. **Take it into your work.** Select papers with `Space`, then press `E` for the export menu. Save BibTeX, RIS, or CSV to a file, or copy Markdown to the clipboard.

Press `?` for help, `Ctrl+p` for the command palette, and `q` to quit. Stars and notes persist when the same papers are loaded again. See [export and collections](https://github.com/NicolasSchuler/arxiv-subscription-viewer/blob/main/docs/export.md) for saved reading lists and metadata backups.

<a id="-choose-a-workflow"></a>

## Choose a workflow

- **Find papers now:** [live searches and local filters](https://github.com/NicolasSchuler/arxiv-subscription-viewer/blob/main/docs/search-filters.md#arxiv-api-search).
- **Review saved emails by date:** [local history and ingestion](https://github.com/NicolasSchuler/arxiv-subscription-viewer/blob/main/docs/history-mode.md).
- **Make a recurring reading brief:** [daily or weekly Markdown digests](https://github.com/NicolasSchuler/arxiv-subscription-viewer/blob/main/docs/digest.md). Email delivery and scheduling use your own tools.

<a id="-highlights"></a>

## Highlights

- **A durable reading queue:** stars, read state, tags, notes, collections, and scheduled reviews.
- **Fast review:** keyboard navigation, structured filters, saved searches, and a quick-triage mode.
- **Portable results:** citation exports, metadata backup, and PDF downloads and previews.
- **Optional research tools:** citation context from Semantic Scholar, Hugging Face paper signals, and summaries or chat through a configured language-model provider.
- **Reading preferences:** **11 themes**, compact lists, and adjustable detail views. See the [configuration reference](https://github.com/NicolasSchuler/arxiv-subscription-viewer/blob/main/docs/config-reference.md).

<a id="-key-bindings"></a>

## Key bindings

The [cheat sheet](https://github.com/NicolasSchuler/arxiv-subscription-viewer/blob/main/docs/cheatsheet.md) covers navigation, organization, research, and export. For the exact keys in your installed version:

```bash
arxiv-viewer keybindings
```

<a id="reading-and-returning"></a>
<a id="marks"></a>

Reading layouts and named paper marks are covered in the [cheat sheet](https://github.com/NicolasSchuler/arxiv-subscription-viewer/blob/main/docs/cheatsheet.md#reading-and-returning).

<a id="-configuration"></a>

## Local data and optional services

Run `arxiv-viewer config-path` to find `config.json`, which stores preferences, review metadata, and session state. Caches normally live in `cache.db` beside it; existing installations may retain separate legacy cache files. Exports default to `~/arxiv-exports/` and PDFs to `~/arxiv-pdfs/`. See [storage and configuration](https://github.com/NicolasSchuler/arxiv-subscription-viewer/blob/main/docs/config-reference.md#file-location).

Saved email text and local review state can be used without a network connection. Live search, uncached abstracts, PDF/figure retrieval, and enabled external integrations use the network. Semantic Scholar, Hugging Face, and LLM enrichment are disabled by default. Configured AI features send paper content and prompts to your chosen CLI or HTTP provider; a local client may still use a hosted service. API keys, when configured, are stored in local JSON.

The base install includes PDF preview support. Optional extras add faster fuzzy matching (`fuzzy`), local embeddings (`semantic-fastembed`, with model downloads), or learned triage (`ml`). See [search setup](https://github.com/NicolasSchuler/arxiv-subscription-viewer/blob/main/docs/search-filters.md), [local triage](https://github.com/NicolasSchuler/arxiv-subscription-viewer/blob/main/docs/history-mode.md#local-triage-model), and [LLM setup](https://github.com/NicolasSchuler/arxiv-subscription-viewer/blob/main/docs/llm-setup.md) before enabling them.

<a id="-shell-completions"></a>
<a id="-upgrade--uninstall"></a>

## Guides and help

- [Documentation index](https://github.com/NicolasSchuler/arxiv-subscription-viewer/blob/main/docs/README.md) — find a guide by task.
- [Cheat sheet](https://github.com/NicolasSchuler/arxiv-subscription-viewer/blob/main/docs/cheatsheet.md) — commands, shortcuts, shell completions, and upgrades.
- [Configuration reference](https://github.com/NicolasSchuler/arxiv-subscription-viewer/blob/main/docs/config-reference.md) — paths, preferences, and optional services.
- [Troubleshooting](https://github.com/NicolasSchuler/arxiv-subscription-viewer/blob/main/docs/troubleshooting.md) — recover from setup, search, and terminal problems.

<a id="-development"></a>

## Contributing

Bug reports, clearer documentation, and focused code changes are welcome. Start with [contributing](https://github.com/NicolasSchuler/arxiv-subscription-viewer/blob/main/CONTRIBUTING.md), or [report an issue](https://github.com/NicolasSchuler/arxiv-subscription-viewer/issues/new/choose) with your version and steps to reproduce. For package boundaries, read the [architecture guide](https://github.com/NicolasSchuler/arxiv-subscription-viewer/blob/main/docs/architecture.md).

<a id="-license"></a>

## License

[MIT](https://github.com/NicolasSchuler/arxiv-subscription-viewer/blob/main/LICENSE) · Created by Nicolas Sebastian Schuler. An independent project; not affiliated with arXiv.
