arXiv Subscription Viewer

Triage arXiv papers from your terminal.
History mode or live API search · keyboard-first review · optional citation and LLM enrichment

🚀 Getting Started

Pick the entry path that matches how you already follow papers:

• history/ workflow: review local daily digests with persistent date navigation, bookmarks, notes, and collections.
• Live arXiv search: start directly from the API when you want the newest matching papers without preparing local files first.

Requires Python 3.13+.

Install

python3.13 --version

uv tool install arxiv-subscription-viewer
# or: python3.13 -m pip install --user arxiv-subscription-viewer

# Optional faster fuzzy matching
uv tool install "arxiv-subscription-viewer[fuzzy]"

First Run

arxiv-viewer doctor

# Start from live arXiv results
arxiv-viewer search --category cs.AI

# Or review a local history/ archive from its parent directory
arxiv-viewer browse

Press ? in-app for help and Ctrl+p for the command palette.

Typical Flow

1. Install the CLI and run arxiv-viewer doctor.
2. Scan papers with arxiv-viewer search ... or arxiv-viewer browse from a history/ archive.
3. Enrich promising papers with Semantic Scholar (e/Ctrl+e), HuggingFace (Ctrl+h), version checks (V), or LLM summaries (Ctrl+s).
4. Organize the queue with read state, stars, tags, notes, bookmarks, marks, collections, and spaced-review scheduling.
5. Export selected papers or collections as BibTeX, RIS, CSV, Markdown, or PDFs.
6. Configure defaults, API keys, export paths, and themes in config.json when the built-in defaults stop being enough.

Common Commands

# Search by topic
arxiv-viewer search --query "diffusion transformer" --field title

# Paginate through results (instead of collecting the newest day)
arxiv-viewer search --query "attention" --mode page --max-results 100

# Generate a cron-friendly Markdown digest
arxiv-viewer digest --category cs.AI --period weekly --output digest.md

# Open the same digest pipeline as an interactive inbox
arxiv-viewer digest --category cs.AI --period weekly --tui

# List local history dates
arxiv-viewer dates

# Inspect or clear local caches
arxiv-viewer cache-info
arxiv-viewer cache-clear --semantic --yes

# Show version
arxiv-viewer --version

# Print config file path
arxiv-viewer config-path

# Print key bindings (supports --format table|json|markdown, --tier core|standard|power|all)
arxiv-viewer keybindings

# Module entrypoint, equivalent to arxiv-viewer
python -m arxiv_browser --version

history/ setup details live in docs/history-mode.md.

Global options: --version · --debug (log to file) · --ascii (ASCII-only icons) · --color auto|always|never · --no-color · --theme NAME (built-in or custom_themes entry)

Debug log paths: ~/.config/arxiv-browser/debug.log (Linux) · ~/Library/Application Support/arxiv-browser/debug.log (macOS) · %APPDATA%/arxiv-browser/debug.log (Windows)

🧭 Choose A Workflow

history/ archive

Run the viewer from the directory that contains your history/ folder:

mkdir -p ~/research/arxiv/history
cd ~/research/arxiv
# Save a digest as history/2026-02-13.txt
arxiv-viewer

This path is best when you review daily digests in order and want persistent local state.

Live arXiv search

Use the API-first path when you want to start from current arXiv results:

arxiv-viewer search --category cs.AI
arxiv-viewer search --query "diffusion transformer" --field title

If something looks off, run arxiv-viewer doctor to check config, history discovery, CLI setup, and environment assumptions.

✨ Highlights

Ctrl+p opens the command palette. Trend Radar, author profiles, the local triage model, paper remix/debate, and other power features are reached through it rather than via a dedicated key.

⌨️ Key Bindings

Marks

Press m followed by a letter (a–z) to set a named mark at the current paper. Press ' followed by that letter to jump back to it. Marks persist within a session, making it easy to navigate between papers you're comparing or revisiting.

⚙️ Configuration

Config lives at ~/.config/arxiv-browser/config.json (Linux), ~/Library/Application Support/arxiv-browser/config.json (macOS), or %APPDATA%/arxiv-browser/config.json (Windows).

Run arxiv-viewer config-path to print the exact path on your machine. API keys for HTTP LLM providers, Semantic Scholar, and embedding services are stored locally in this file; use normal filesystem permissions and avoid committing it.

If you want the best documentation entry point for your context:

• 🌐 Published guide hub: nicolasschuler.github.io/arxiv-subscription-viewer
• 📚 Repository docs index: docs/README.md
• ⚙️ Direct config reference: docs/config-reference.md

See the full documentation for:

• 🧭 Docs start page
• 🗺️ Quick reference / cheat sheet
• 🌐 Published docs landing page
• ⚙️ Configuration reference
• 🤖 AI summary & LLM setup
• 📊 Semantic Scholar integration
• 🔥 HuggingFace trending
• 📅 History mode & email ingestion
• 📨 Markdown digests & automation
• 🔍 Search filters & advanced queries
• 📥 Export & PDF configuration
• 🛠️ Troubleshooting

🐚 Shell Completions

Enable tab completion for subcommands and flags:

# Bash (add to ~/.bashrc)
eval "$(arxiv-viewer completions bash)"

# Zsh (add to ~/.zshrc)
eval "$(arxiv-viewer completions zsh)"

# Fish (add to ~/.config/fish/config.fish)
arxiv-viewer completions fish | source

🔄 Upgrade / Uninstall

uv tool upgrade arxiv-subscription-viewer
uv tool uninstall arxiv-subscription-viewer

# pip-installed users
python3.13 -m pip install --user --upgrade arxiv-subscription-viewer
python3.13 -m pip uninstall arxiv-subscription-viewer

🛠️ Development

git clone https://github.com/NicolasSchuler/arxiv-subscription-viewer.git
cd arxiv-subscription-viewer
uv python install 3.13
uv sync --locked
pre-commit install
just check   # docs drift + lint + typechecks + tests
just quality # full local quality suite

For contributor-oriented architecture and import-boundary guidance, start with docs/architecture.md.

📄 License

MIT — Nicolas Sebastian Schuler