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.
Application capture from the development checkout, using fictional paper fixtures. The released interface may differ.
Website · Guides · PyPI · Changelog
Getting started
Install
Use uv 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.
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:
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 includes a complete input example.
If the command is missing or results do not load, follow first-run troubleshooting. arxiv-viewer doctor diagnoses your setup; warnings about optional features are not prerequisites for live search.
Install with pip instead
With Python 3.13+ installed, create and activate a virtual environment:
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.
Typical flow
- Scan. Move with
j/kor the arrow keys. Read the selected abstract in the details pane. - Keep what matters. Press
xto star a paper,nto add a note, andrto mark it read. - Narrow the list. Press
/and enterstarredorunread. This filters the papers already loaded;Astarts a new arXiv search. - Take it into your work. Select papers with
Space, then pressEfor 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 for saved reading lists and metadata backups.
Choose a workflow
- Find papers now: live searches and local filters.
- Review saved emails by date: local history and ingestion.
- Make a recurring reading brief: daily or weekly Markdown digests. Email delivery and scheduling use your own tools.
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.
Key bindings
The cheat sheet covers navigation, organization, research, and export. For the exact keys in your installed version:
arxiv-viewer keybindings
Reading layouts and named paper marks are covered in the cheat sheet.
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.
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, local triage, and LLM setup before enabling them.
Guides and help
- Documentation index — find a guide by task.
- Cheat sheet — commands, shortcuts, shell completions, and upgrades.
- Configuration reference — paths, preferences, and optional services.
- Troubleshooting — recover from setup, search, and terminal problems.
Contributing
Bug reports, clearer documentation, and focused code changes are welcome. Start with contributing, or report an issue with your version and steps to reproduce. For package boundaries, read the architecture guide.
License
MIT · Created by Nicolas Sebastian Schuler. An independent project; not affiliated with arXiv.
Metadata
Release files for arxiv-subscription-viewer 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| arxiv_subscription_viewer-0.4.0.tar.gz | 1.5 MB | With provenance | Details for arxiv_subscription_viewer-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| arxiv_subscription_viewer-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for arxiv_subscription_viewer-0.4.0-py3-none-any.whl |
Total release size: 1.9 MB
Release files / arxiv_subscription_viewer-0.4.0.tar.gz
| Download URL | arxiv_subscription_viewer-0.4.0.tar.gz |
|---|---|
| Size | 1.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
60e32f612043c311c683f1a559461e830e1898e474086464f1629d5dbac397a9
|
|
BLAKE2b-256 checksum How to use checksums |
2b3717ce9f1354314559b2b096cfe2897feb4a36127498735a4ad8f7b88a249b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 4, 2026.
Transparency logRelease files / arxiv_subscription_viewer-0.4.0-py3-none-any.whl
| Download URL | arxiv_subscription_viewer-0.4.0-py3-none-any.whl |
|---|---|
| Size | 421.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
843cedc8125596e80475ce5a2b5ee210e5120c94d3bdb77c08da5c9ff1e03e0e
|
|
BLAKE2b-256 checksum How to use checksums |
79a10da10808316e5a280ba0169959fce9b7fc517caf972b3f3dccfdd52e1d99
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 4, 2026.
Transparency logSecurity for arxiv-subscription-viewer 0.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for arxiv_subscription_viewer-0.4.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 4, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.