A CLI tool for managing academic papers with knowledge base and vector search support.
- Semantic search — FAISS vector indexing with configurable embedding models, query your papers by meaning rather than keywords
- Add papers by DOI — automatically download Open Access PDFs via Unpaywall API with
--doi(integration guide) - PDF metadata extraction — automatically extracts title, author, keywords, DOI, and more from PDF files
- DOI deduplication — detects duplicate papers by DOI before adding, with
--forceoverride - Multi-format support — import from PDF, TXT, MD, TEX, and other text-based formats
- PDF-to-Markdown conversion — optional high-quality conversion via opendataloader-pdf with image extraction (integration guide)
- Dual-scope data model — user-level (
~/.paper-manager/) for global collections and project-level (./.paper-manager/) for project-specific papers, with automatic scope resolution - DOI-to-BibTeX — convert DOI to BibTeX citation in one command
- Machine-readable output —
--jsonand--jqflags on all read commands for scripting and automation - Literature notes — attach key-value annotations to any paper
- Local-first — SQLite + FAISS + filesystem, no cloud dependencies
- Agent skill — installable as a coding agent skill for agent-driven paper management
npm install -g paper-managerpnpm install -g paper-managerbun install -g paper-manager# Initialize data directory
paper config init --user
# Configure an embedding model
paper config set embeddingModels '{"openai-small":{"provider":"openai","model":"text-embedding-3-small","apiKey":"sk-...","dimensions":1536}}' --user
paper config set defaultEmbeddingModelId '"openai-small"' --user
# Create a knowledge base
paper kb create my-papers -d "My research papers"
# Add a paper (supports PDF, TXT, MD, TEX, etc.)
paper lit add <knowledge-base-id> ./paper.pdf
# Or add an Open Access paper by DOI
paper config set email '"you@example.com"' --user # one-time setup for Unpaywall API
paper lit add <knowledge-base-id> --doi 10.1038/nature12373
# Search across papers
paper kb query <knowledge-base-id> "attention mechanism"paper config init [--user] # Initialize data directory structure
paper config get <key> [--user] # Get a config value
paper config set <key> <value> [--user] # Set a config value
paper config remove <key> [--user] # Remove a config key
paper config list [--user] # List all configpaper kb create <name> -d <desc> [-e <model-id>] [--user] # Create a knowledge base
paper kb list [--all | --user] [--json] [--jq <expr>] # List knowledge bases
paper kb update <id> [-n <name>] [-d <desc>] # Update knowledge base metadata
paper kb remove <id> # Remove a knowledge base
paper kb query <id> <query-text> [--json] [--jq <expr>] # Query a knowledge basepaper lit add <kb-id> <file-path> [-f] # Add a literature from file (auto-extracts PDF metadata)
paper lit add <kb-id> --doi <doi> [-f] # Add an Open Access paper by DOI via Unpaywall
paper lit remove <kb-id> <id> # Remove a literature
paper lit update <kb-id> <id> [opts] # Update literature metadata
paper lit list <kb-id> [--json] [--jq <expr>] # List literatures
paper lit search <kb-id> [opts] [--json] [--jq <expr>] # Search literatures by metadata
paper lit show <kb-id> <id> [--json] [--jq <expr>] # Show literature details
paper lit note list <lit-id> [--json] [--jq <expr>] # List notes
paper lit note set <lit-id> <k> <v> # Set a note
paper lit note remove <lit-id> <key> # Remove a notepaper util doi2bib <doi> # Convert a DOI to BibTeX citation
paper util pdf-meta <file> [--json] [--jq <expr>] # Extract metadata from a PDF file# Initialize a project-scoped data directory (version-controllable)
paper config init
# Create a knowledge base for your topic
paper kb create "llm-agents" -d "Papers on LLM-based autonomous agents"
# Output: Knowledge base created: 9f3a...
# Add papers — by file or by DOI
paper lit add 9f3a ./downloaded-paper.pdf
paper lit add 9f3a --doi 10.48550/arXiv.2305.10601
# Ask questions across all your papers
paper kb query 9f3a "how do agents handle long-term memory?"# Spot a DOI in a reference list? One command to ingest it.
paper lit add <kb-id> --doi 10.1038/nature12373
# Unpaywall checks OA status, downloads the PDF, extracts metadata,
# and builds a vector index — all in one step.
# If the paper is not OA, you'll get a clear error with instructions.paper util doi2bib 10.1145/3586183.3606763
# @inproceedings{...}
# Combine with jq to batch-extract DOIs from your knowledge base
paper lit list <kb-id> --jq '.[].doi | select(. != null)'# Export all papers in a knowledge base as JSON
paper lit list <kb-id> --json > papers.json
# Filter with jq expressions inline
paper lit list <kb-id> --jq '[.[] | {title, doi, author}]'
# Find papers by a specific author
paper lit search <kb-id> -a "Vaswani" --json# Attach notes to track your reading progress
paper lit note set <lit-id> status "read"
paper lit note set <lit-id> relevance "high"
paper lit note set <lit-id> summary "Proposes transformer architecture..."
# Review all notes
paper lit note list <lit-id>See Configuration Reference for all available config fields and detailed usage.
- User data:
~/.paper-manager/— global config, personal knowledge bases - Project data:
./.paper-manager/— project-specific knowledge bases
Project config takes priority over user config.
Install as a skill to let coding agent manage your papers (Powered by vercel-labs/skills):
npx skills add https://github.com/EurFelux/paper-managerpnpx skills add https://github.com/EurFelux/paper-managerbunx skills add https://github.com/EurFelux/paper-manager